Documentation
¶
Overview ¶
Package openapi generates OpenAPI 3.1 documents from Go types and validator tags.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidOption = errors.New("openapi: invalid option") ErrInvalidOperation = errors.New("openapi: invalid operation") ErrOperationExists = errors.New("openapi: operation already exists") )
Errors returned for invalid generator configuration and operations.
Functions ¶
func DocsHTML ¶
DocsHTML returns a self-contained documentation page rendering the spec at specURL with Scalar (https://github.com/scalar/scalar).
Types ¶
type Components ¶
Components contains reusable schemas.
type Document ¶
type Document struct {
OpenAPI string `json:"openapi"`
Info Info `json:"info"`
Paths map[string]PathItem `json:"paths,omitempty"`
Components *Components `json:"components,omitempty"`
}
Document is the generated OpenAPI 3.1 document.
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator accumulates operations. It is not safe for concurrent use.
func (*Generator) Add ¶
func (g *Generator) Add[Request any](method, path string, opts ...OperationOption) error
Add registers an operation. At least one WithResponse or WithDefaultResponse option is required. Generation is transactional: an error leaves paths, components, and schema-name allocation unchanged.
type MediaType ¶
type MediaType struct {
Schema *Schema `json:"schema,omitempty"`
}
MediaType associates content with a schema.
type NoBody ¶ added in v0.2.1
type NoBody struct{}
NoBody marks a request or response without JSON content.
type Operation ¶
type Operation struct {
Summary string `json:"summary,omitempty,omitzero"`
Tags []string `json:"tags,omitempty"`
Parameters []*Parameter `json:"parameters,omitempty"`
RequestBody *RequestBody `json:"requestBody,omitempty"`
Responses map[string]*Response `json:"responses"`
}
Operation describes one HTTP operation.
type OperationOption ¶ added in v0.2.1
type OperationOption func(*operationConfig) error
OperationOption configures one operation.
func WithDefaultResponse ¶ added in v0.2.1
func WithDefaultResponse[Body any](opts ...ResponseOption) OperationOption
WithDefaultResponse adds the OpenAPI "default" response.
func WithResponse ¶ added in v0.2.1
func WithResponse[Body any](status int, opts ...ResponseOption) OperationOption
WithResponse adds a status response whose JSON body is Body. Use NoBody for responses without content.
func WithSummary ¶ added in v0.2.1
func WithSummary(summary string) OperationOption
WithSummary sets the operation summary.
func WithTags ¶ added in v0.2.1
func WithTags(tags ...string) OperationOption
WithTags appends non-empty operation tags.
type Option ¶
Option configures a Generator.
func WithSchema ¶ added in v0.2.1
WithSchema replaces the inferred schema for T. The input is copied.
func WithValidator ¶
WithValidator selects the Validator used to inspect validate tags.
type Parameter ¶
type Parameter struct {
Name string `json:"name"`
In string `json:"in"` // "path" or "query"
Required bool `json:"required,omitempty,omitzero"`
Schema *Schema `json:"schema,omitempty"`
}
Parameter describes a path or query parameter.
type RequestBody ¶
type RequestBody struct {
Required bool `json:"required,omitempty,omitzero"`
Content map[string]*MediaType `json:"content"`
}
RequestBody describes a JSON request body.
type Response ¶
type Response struct {
Description string `json:"description"`
Content map[string]*MediaType `json:"content,omitempty"`
}
Response describes one HTTP response.
type ResponseOption ¶ added in v0.2.1
type ResponseOption func(*responseOptions) error
ResponseOption configures one response.
func ResponseDescription ¶ added in v0.2.1
func ResponseDescription(description string) ResponseOption
ResponseDescription overrides the default HTTP status description.
type Schema ¶
type Schema struct {
Ref string `json:"$ref,omitempty,omitzero"`
Type string `json:"type,omitempty,omitzero"`
Format string `json:"format,omitempty,omitzero"`
Description string `json:"description,omitempty,omitzero"`
Properties map[string]*Schema `json:"properties,omitempty"`
Items *Schema `json:"items,omitempty"`
AdditionalProperties *Schema `json:"additionalProperties,omitempty"`
Required []string `json:"required,omitempty"`
Enum []any `json:"enum,omitempty"`
Pattern string `json:"pattern,omitempty,omitzero"`
Minimum *float64 `json:"minimum,omitempty"`
Maximum *float64 `json:"maximum,omitempty"`
ExclusiveMinimum *float64 `json:"exclusiveMinimum,omitempty"`
ExclusiveMaximum *float64 `json:"exclusiveMaximum,omitempty"`
MinLength *uint64 `json:"minLength,omitempty"`
MaxLength *uint64 `json:"maxLength,omitempty"`
MinItems *uint64 `json:"minItems,omitempty"`
MaxItems *uint64 `json:"maxItems,omitempty"`
UniqueItems bool `json:"uniqueItems,omitempty,omitzero"`
// ContentEncoding marks base64 payloads ([]byte fields), per JSON Schema 2020-12.
ContentEncoding string `json:"contentEncoding,omitempty,omitzero"`
}
Schema is the JSON Schema subset used by both parameters and bodies.
Source Files