Documentation
¶
Overview ¶
Package openapi provides utilities for generating, serving, and filtering OpenAPI specifications, as well as rendering interactive API documentation using providers such as Scalar, Stoplight Elements, and Swagger UI.
Index ¶
- func DefineErrors(op *core.Operation, registry core.Registry, factory core.ErrorHandler, ...)
- func Downgrade(oapi *core.OpenAPI) ([]byte, error)
- func DowngradeYAML(oapi *core.OpenAPI) ([]byte, error)
- func FilterByTag(oapi *core.OpenAPI, tag string) *core.OpenAPI
- func FilterExcludeTag(oapi *core.OpenAPI, tag string) *core.OpenAPI
- func GenerateInternalSpec(oapi *core.OpenAPI, hiddenOps []*core.Operation) (*core.OpenAPI, error)
- func GenerateInternalSpecJSON(oapi *core.OpenAPI, hiddenOps []*core.Operation) ([]byte, error)
- func RegisterDocsRoute(adapter core.Adapter, oapi *core.OpenAPI, config core.Config)
- func RegisterErrorDocRoutes(adapter core.Adapter, factory core.ErrorHandler, config core.Config)
- func RegisterInternalSpecRoutes(adapter core.Adapter, api core.API, config core.Config)
- func RegisterSpecRoutes(adapter core.Adapter, oapi *core.OpenAPI, config core.Config)
- func YAML(oapi *core.OpenAPI) ([]byte, error)
- type ScalarProvider
- type SchemaLinkTransformer
- type StoplightProvider
- type SwaggerUIProvider
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefineErrors ¶
func DefineErrors(op *core.Operation, registry core.Registry, factory core.ErrorHandler, discovered ...[]core.DiscoveredError)
DefineErrors populates the error responses on an operation based on its declared error status codes, the error schema from the factory, and any discovered errors.
func Downgrade ¶
Downgrade converts an OpenAPI 3.1+ spec to OpenAPI 3.0 compatible JSON by transforming features like type arrays, exclusive min/max, and content encoding.
func DowngradeYAML ¶
DowngradeYAML converts an OpenAPI 3.1+ spec to OpenAPI 3.0 compatible YAML.
func FilterByTag ¶
FilterByTag returns a copy of the OpenAPI spec containing only operations that have the specified tag.
func FilterExcludeTag ¶
FilterExcludeTag returns a copy of the OpenAPI spec with all operations that have the specified tag removed.
func GenerateInternalSpec ¶
GenerateInternalSpec returns a copy of the OpenAPI spec with hidden operations merged in, intended for internal-only consumption.
func GenerateInternalSpecJSON ¶
GenerateInternalSpecJSON returns the internal OpenAPI spec as JSON, including hidden operations, hidden parameters, and hidden schema properties.
func RegisterDocsRoute ¶
RegisterDocsRoute registers an HTTP route that serves an interactive API documentation page using the configured documentation provider.
func RegisterErrorDocRoutes ¶
RegisterErrorDocRoutes registers HTTP routes that serve human-readable error documentation pages (HTML and JSON) for each HTTP status code used by the API.
func RegisterInternalSpecRoutes ¶
RegisterInternalSpecRoutes registers HTTP routes that serve the internal OpenAPI spec (JSON and YAML) and an internal documentation page.
func RegisterSpecRoutes ¶
RegisterSpecRoutes registers HTTP routes that serve the public OpenAPI spec in JSON and YAML formats, and optionally individual schema routes.
Types ¶
type ScalarProvider ¶
type ScalarProvider struct {
LocalJSPath string
}
ScalarProvider renders API documentation using the Scalar UI. Set LocalJSPath to serve the Scalar JavaScript bundle from a local path instead of the CDN.
type SchemaLinkTransformer ¶ added in v1.1.0
type SchemaLinkTransformer struct {
// contains filtered or unexported fields
}
SchemaLinkTransformer adds a Link header with rel="describedBy" and a $schema field to JSON response bodies, pointing to the JSON Schema that describes the response structure (RFC 8288).
func NewSchemaLinkTransformer ¶ added in v1.1.0
func NewSchemaLinkTransformer(schemasPath string) *SchemaLinkTransformer
NewSchemaLinkTransformer creates a transformer that adds a Link header with rel="describedBy" and a $schema field to response bodies.
func (*SchemaLinkTransformer) OnAddOperation ¶ added in v1.1.0
func (t *SchemaLinkTransformer) OnAddOperation(oapi *core.OpenAPI, op *core.Operation)
OnAddOperation is triggered whenever a new operation is added to the API, enabling this transformer to precompute and cache information about the response and schema.
type StoplightProvider ¶
type StoplightProvider struct{}
StoplightProvider renders API documentation using Stoplight Elements.
type SwaggerUIProvider ¶
SwaggerUIProvider renders API documentation using Swagger UI. Set OAuthClientID and OAuthScopes to enable OAuth2 authorization in the UI.
Source Files