Documentation
¶
Overview ¶
Package openapi writes the OpenAPI document describing a mux's endpoints: one operation per endpoint, taking and returning the types the endpoint declares, so that what the document says and what the server does come from one source.
It is the sibling of pkg/http/client_code_generation, which reads the same hints to write a typed client. Where the two could disagree -- how an input is carried, what counts as a binary body, what an operation is called -- they are made to agree, because a document and a client that describe the same endpoint differently are worse than either alone.
Which endpoints are documented ¶
Those whose hint sets Hint.Documented, and no others. An endpoint is not offered to third parties until someone decides it should be, so a service that declares no documented endpoint gets a document with no operations rather than one describing everything it happens to serve.
Two further exclusions are not decisions anyone makes: an endpoint with no hint says nothing about what it takes or returns, and one serving static content is a document rather than an operation.
Version ¶
The document is written against OpenAPI 3.2 by default, which is the first version with a field for the HTTP QUERY method. A document targeting 3.1 is otherwise the same, and an endpoint served as QUERY is refused rather than written as something it is not.
Index ¶
- Constants
- func Generate(endpoints []*endpointPkg.Endpoint, options ...openapi_config.Option) (*openapiTypes.Document, error)
- func MakeOperation(endpoint *endpointPkg.Endpoint, context *jsonschemaTypes.Context, ...) (*openapiTypes.Operation, error)
- func MakeParameters(reflectType reflect.Type) ([]*openapiTypes.Parameter, error)
- func Marshal(document *openapiTypes.Document) ([]byte, error)
- func NewEndpoint(data []byte, options ...openapi_config.Option) (*endpointPkg.Endpoint, error)
- func Run(arguments []string, endpoints []*endpointPkg.Endpoint, ...) int
Constants ¶
const BodyValidationProblemDetailSchemaName = "BodyValidationProblemDetail"
BodyValidationProblemDetailSchemaName is what the problem detail carrying validation errors is called in a document's components.
const ComponentsRefPrefix = "#/components/schemas/"
ComponentsRefPrefix is where a document keeps the schemas its operations refer to.
const MethodQuery = "QUERY"
MethodQuery is the HTTP QUERY method: a safe, idempotent read whose parameters travel in the request body. net/http defines no constant for it.
const ProblemDetailContentType = "application/problem+json"
ProblemDetailContentType is what a problem detail is served as.
const ProblemDetailSchemaName = "ProblemDetail"
ProblemDetailSchemaName is what the problem detail schema is called in a document's components.
Variables ¶
This section is empty.
Functions ¶
func Generate ¶
func Generate(endpoints []*endpointPkg.Endpoint, options ...openapi_config.Option) (*openapiTypes.Document, error)
Generate writes the document describing the endpoints.
func MakeOperation ¶
func MakeOperation( endpoint *endpointPkg.Endpoint, context *jsonschemaTypes.Context, securitySchemeNames []string, refPrefix string, ) (*openapiTypes.Operation, error)
MakeOperation describes one endpoint as an operation.
func MakeParameters ¶
func MakeParameters(reflectType reflect.Type) ([]*openapiTypes.Parameter, error)
MakeParameters describes a query struct as the query parameters an operation takes.
The walk is the query extractor's own, rather than the JSON schema exporter's, because the two accept different things: the extractor reads the query tag where the exporter reads the jsonschema tag, refuses pointers where the exporter makes them nullable, and imposes none of the minimum length the exporter puts on every string. A parameter list built the other way would document a request the server would refuse and refuse one it accepts.
A nil or empty-interface type has no parameters, which is not an error: most endpoints take none.
func Marshal ¶
func Marshal(document *openapiTypes.Document) ([]byte, error)
Marshal writes the document as the bytes it is served and committed as.
The same document marshals to the same bytes every time: schemas are maps, and json/v2 does not order a map's members unless it is told to. A document that reordered itself between runs would make a committed copy re-diff on every generation, and the diff is the point of committing it.
func NewEndpoint ¶
func NewEndpoint(data []byte, options ...openapi_config.Option) (*endpointPkg.Endpoint, error)
NewEndpoint serves the document as static content, pre-compressed and tagged, the way any other body that does not change between requests is served.
It is gated unless the configuration says otherwise. The document names every operation the service offers, what each takes and what each returns; handing that to an unauthenticated reader is a decision, and the default is not to make it silently.
func Run ¶
func Run(arguments []string, endpoints []*endpointPkg.Endpoint, options ...openapi_config.Option) int
Run writes the document describing the endpoints, as a program.
The options carry what no endpoint can supply -- the title, the version, the security schemes -- and the arguments carry what belongs on a command line. A caller is a main of a dozen lines that hands over its own endpoints, so that the flags, the writing and the drift check are written once rather than per service.
Types ¶
This section is empty.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package types holds the OpenAPI document model: the objects a document is made of, shaped so that marshalling one produces the document.
|
Package types holds the OpenAPI document model: the objects a document is made of, shaped so that marshalling one produces the document. |