Documentation
¶
Overview ¶
Package openapi generates an OpenAPI 3.1 document from the router: typed routes (api.Register) are described from their input and output types and `validate` tags; plain routes get a generic entry.
doc := openapi.Generate(r.Routes(), openapi.Info{Title: "Shop", Version: "1.0.0"})
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoOperation = errors.New("openapi: no operation matches the request")
ErrNoOperation is returned when the document has no operation for the request.
Functions ¶
func TypeScript ¶
TypeScript returns TypeScript declarations for the document: one type per component schema, plus <Operation>Body, <Operation>Query and <Operation>Response for every operation with an operationId. With zod set, Zod schemas (<Name>Schema) for the components follow the types.
Types ¶
type Components ¶
type Components struct {
Schemas map[string]Schema `json:"schemas,omitempty"`
Responses map[string]Response `json:"responses,omitempty"`
SecuritySchemes map[string]Schema `json:"securitySchemes,omitempty"`
}
Components holds reusable schemas, responses and security schemes.
type Document ¶
type Document struct {
OpenAPI string `json:"openapi"`
Info docInfo `json:"info"`
Servers []server `json:"servers,omitempty"`
Paths map[string]map[string]*Operation `json:"paths"`
Components Components `json:"components"`
}
Document is an OpenAPI 3.1 document.
func (*Document) ValidateResponse ¶
ValidateResponse checks a response body against the document: the operation for method and path (a concrete URL path), then the schema declared for status, or the "default" response. It supports the JSON Schema subset Generate emits.
type Info ¶
type Info struct {
Title string
Version string
Description string
Servers []string
// PathPrefix keeps only routes under it (e.g. "/api"); empty keeps all.
PathPrefix string
// SecuritySchemes adds or replaces schemes; "bearer" (HTTP bearer
// token) is predefined.
SecuritySchemes map[string]Schema
}
Info configures the document.
type MediaType ¶
type MediaType struct {
Schema Schema `json:"schema"`
}
MediaType wraps a schema for one content type.
type Operation ¶
type Operation struct {
OperationID string `json:"operationId,omitempty"`
Summary string `json:"summary,omitempty"`
Description string `json:"description,omitempty"`
Tags []string `json:"tags,omitempty"`
Deprecated bool `json:"deprecated,omitempty"`
Parameters []Parameter `json:"parameters,omitempty"`
RequestBody *RequestBody `json:"requestBody,omitempty"`
Responses map[string]Response `json:"responses"`
Security []map[string][]string `json:"security,omitempty"`
}
Operation is one method on a path.
type Parameter ¶
type Parameter struct {
Name string `json:"name"`
In string `json:"in"`
Required bool `json:"required,omitempty"`
Description string `json:"description,omitempty"`
Schema Schema `json:"schema"`
}
Parameter is a path or query parameter.
type RequestBody ¶
type RequestBody struct {
Required bool `json:"required"`
Content map[string]MediaType `json:"content"`
}
RequestBody is an operation's body.
type Response ¶
type Response struct {
Ref string `json:"$ref,omitempty"`
Description string `json:"description,omitempty"`
Content map[string]MediaType `json:"content,omitempty"`
}
Response is a response or a $ref to a shared one.
type Schemas ¶
type Schemas struct {
// contains filtered or unexported fields
}
Schemas turns Go types into JSON Schemas, collecting named structs as reusable components. Constraints come from the same `validate` tags the z package enforces, so the document matches what the server accepts.
func (*Schemas) Components ¶
Components returns the named schemas collected so far.
Source Files