Documentation
¶
Overview ¶
Package openapi turns Go request and response types into OpenAPI 3.1 (JSON Schema draft 2020-12) component schemas and parameters.
It uses compose's copy of the huma/v2 schema generator (internal/huma; no huma router, API or validator) behind its own huma.Registry implementation, which adds compose specifics: package-qualified component names, uuid and compose types formats, enums.Set types as named enum components, request parameters from path/query/header tags, presence-required request variants, a struct tag lint and the removal of additionalProperties:false from published schemas.
Usage: create a Reflector, call AddRequest/AddResponse for every operation type, then Finalize once to obtain the Result.
Index ¶
Constants ¶
const RefPrefix = "#/components/schemas/"
RefPrefix is the prefix of every $ref produced by the Reflector.
Variables ¶
This section is empty.
Functions ¶
func DefaultNamer ¶
DefaultNamer returns `<lastPathSegment>.<TypeName>`. Generic arguments are package-qualified too: Page[a.User] becomes `pkg.Page_a.User`. It is SegmentsNamer(1).
func IsOptional ¶
IsOptional reports whether t, or the type it points to, is a types.Optional.
func SegmentsNamer ¶
SegmentsNamer returns a namer that qualifies type names (and generic arguments) with the last n package path segments joined by ".": SegmentsNamer(2) names finance/units.ListRequest `finance.units.ListRequest`. n below 1 is treated as 1.
Types ¶
type Param ¶
type Param struct {
Name string // wire name, header names lowercased
In string // "path" | "query" | "header"
Required bool // always true for path params, which refuse required:"false"
Schema *huma.Schema // inline schema (may be a $ref for enum types); Description lives in Doc
Index []int // reflect field index path into the request struct
Doc string // from doc tag
Deprecated bool
}
Param is a path, query or header parameter of a request type.
type Reflector ¶
type Reflector struct {
// contains filtered or unexported fields
}
Reflector collects request and response types and produces components. It is not safe for concurrent use.
func NewReflector ¶
NewReflector returns an empty Reflector.
func (*Reflector) AddRequest ¶
AddRequest registers t (struct or pointer to struct) as a request root, lints it, and returns its parameters. Idempotent for the same t.
func (*Reflector) AddResponse ¶
AddResponse registers t (struct, pointer to struct, or slice/map thereof) as a response type. Idempotent. Returns lint errors, and an error when a struct it reaches sends a JSON key its schema does not list (see checkKeys).
type Result ¶
type Result struct {
// Components keyed by name, ready to place under #/components/schemas.
Components map[string]*huma.Schema
// contains filtered or unexported fields
}
Result holds the finalized components. It is shared and must not be mutated: accessor methods return copies, and Components must be treated as read-only (copy before editing).
func (*Result) BodyRef ¶
BodyRef returns the $ref and whether the body is required (the schema has at least one required property) for a request root type. ok is false when the type has no body properties (all fields are params or hidden).
func (*Result) ResponseSchema ¶
ResponseSchema returns a copy of the schema for a response root type: a $ref for structs, an inline schema for slices and maps. nil when t was not registered.
func (*Result) StrictComponents ¶
StrictComponents returns a deep copy of Components with additionalProperties:false re-injected on every object component reachable from a response root, and with hidden properties listed, so a hidden field a response sends is a known field checked against its schema (for contract tests). Hidden properties stay optional.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
fixture
Package fixture mirrors auditor3's runs module for openapi reflector tests.
|
Package fixture mirrors auditor3's runs module for openapi reflector tests. |
|
fixture/a/units
Package units collides by last path segment with fixture/b/units.
|
Package units collides by last path segment with fixture/b/units. |
|
fixture/b/units
Package units collides by last path segment with fixture/a/units.
|
Package units collides by last path segment with fixture/a/units. |
|
fixture/other
Package other holds a type whose name collides with fixture.Run, to prove package-qualified component names keep them apart.
|
Package other holds a type whose name collides with fixture.Run, to prove package-qualified component names keep them apart. |