Documentation
¶
Overview ¶
Package openapi renders schema.Schema values as OpenAPI 3.x schema objects.
It imports only the schema package — no codec logic is involved. Renderers read pure schema data; codecs write it. This separation means the same schema.Schema can be used by multiple renderers without any coupling.
Typical usage:
named := map[string]schema.Schema{
"User": UserCodec.Schema,
}
out, err := openapi.MarshalYAML(named)
document.go provides DocumentBuilder for assembling a full OpenAPI 3.1 document from route descriptors and named schemas.
Index ¶
- func ComponentsSchemas(named map[string]schema.Schema) map[string]any
- func MarshalJSON(named map[string]schema.Schema) ([]byte, error)
- func MarshalYAML(named map[string]schema.Schema) ([]byte, error)
- func SchemaObject(s schema.Schema) map[string]any
- type Document
- type DocumentBuilder
- func (b *DocumentBuilder) AddGlobalSecurity(reqs ...route.SecurityRequirement) *DocumentBuilder
- func (b *DocumentBuilder) AddRoute(r route.Route) *DocumentBuilder
- func (b *DocumentBuilder) AddSchema(name string, s schema.Schema) *DocumentBuilder
- func (b *DocumentBuilder) AddSecurityScheme(name string, s route.SecurityScheme) *DocumentBuilder
- func (b *DocumentBuilder) AddServer(s Server) *DocumentBuilder
- func (b *DocumentBuilder) Build() (Document, error)
- type Info
- type Server
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ComponentsSchemas ¶
ComponentsSchemas produces the map suitable for embedding as the value of components.schemas in an OpenAPI 3.x document.
func MarshalJSON ¶
MarshalJSON renders the named schemas as the JSON bytes of a components/schemas map, suitable for embedding in a larger OpenAPI document.
func MarshalYAML ¶
MarshalYAML renders the named schemas as the YAML bytes of a components/schemas map, suitable for embedding in a larger OpenAPI document.
Types ¶
type Document ¶
type Document struct {
// contains filtered or unexported fields
}
Document is a full OpenAPI 3.1 document produced by DocumentBuilder. Use MarshalJSON or MarshalYAML to serialise it.
func (Document) MarshalJSON ¶
MarshalJSON encodes the document as JSON bytes.
func (Document) MarshalYAML ¶
MarshalYAML encodes the document as YAML bytes.
type DocumentBuilder ¶
type DocumentBuilder struct {
// contains filtered or unexported fields
}
DocumentBuilder accumulates routes and named schemas, then produces a Document.
func NewDocumentBuilder ¶
func NewDocumentBuilder(info Info) *DocumentBuilder
NewDocumentBuilder returns a builder initialised with the given Info.
func (*DocumentBuilder) AddGlobalSecurity ¶ added in v0.8.0
func (b *DocumentBuilder) AddGlobalSecurity(reqs ...route.SecurityRequirement) *DocumentBuilder
AddGlobalSecurity appends security requirements that apply to all operations by default. Per-route Security on a route.Route overrides the global list for that operation; an empty per-route slice marks the operation as unsecured.
func (*DocumentBuilder) AddRoute ¶
func (b *DocumentBuilder) AddRoute(r route.Route) *DocumentBuilder
AddRoute appends a route to the document.
func (*DocumentBuilder) AddSchema ¶
func (b *DocumentBuilder) AddSchema(name string, s schema.Schema) *DocumentBuilder
AddSchema registers a named schema in components/schemas. Explicitly registered schemas take precedence over schemas inferred from routes.
func (*DocumentBuilder) AddSecurityScheme ¶ added in v0.8.0
func (b *DocumentBuilder) AddSecurityScheme(name string, s route.SecurityScheme) *DocumentBuilder
AddSecurityScheme registers a named security scheme in components/securitySchemes. The name must match those used in SecurityRequirement maps on routes and in AddGlobalSecurity calls.
func (*DocumentBuilder) AddServer ¶
func (b *DocumentBuilder) AddServer(s Server) *DocumentBuilder
AddServer appends a server to the document.
func (*DocumentBuilder) Build ¶
func (b *DocumentBuilder) Build() (Document, error)
Build validates the accumulated routes and produces a Document.
Validation:
- Duplicate (method, path) pairs are rejected.
- Path parameter names must exactly match the {param} placeholders in the path.
- Path parameters are always treated as required.
Source Files