Documentation
¶
Overview ¶
Package openapi builds the OpenAPI 3.1 document of a chok App from its route table by reflecting over each route's request and response types.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var BearerAuth = Scheme{Name: "bearerAuth", Type: "http", Scheme: "bearer", BearerFormat: "JWT"}
BearerAuth is the scheme of a JWT in the Authorization header.
Functions ¶
Types ¶
type Operation ¶
type Operation struct {
Method, Path string
Summary string
Tags []string
Status int
Deprecated bool
// Security is the schemes the route's authentication middleware
// accepts, any one of them; none for a route without one.
Security []Scheme
// Request is the bound request type; nil or chok.None documents no
// parameters and no body.
Request reflect.Type
// Response is the success body type; nil documents no body.
Response reflect.Type
// ListItem and Filters describe a List route: the item type and the
// query fields it filters on.
ListItem reflect.Type
Filters []string
}
Operation is one documented route.
type Schema ¶
type Schema struct {
Ref string `json:"$ref,omitzero"`
Type any `json:"type,omitzero"` // a name, or [name, "null"]
Format string `json:"format,omitzero"`
Description string `json:"description,omitzero"`
Properties map[string]*Schema `json:"properties,omitzero"`
Required []string `json:"required,omitzero"`
Items *Schema `json:"items,omitzero"`
AdditionalProperties *Schema `json:"additionalProperties,omitzero"`
Enum []any `json:"enum,omitzero"`
Minimum *float64 `json:"minimum,omitzero"`
Maximum *float64 `json:"maximum,omitzero"`
ExclusiveMinimum *float64 `json:"exclusiveMinimum,omitzero"`
ExclusiveMaximum *float64 `json:"exclusiveMaximum,omitzero"`
MinLength *int `json:"minLength,omitzero"`
MaxLength *int `json:"maxLength,omitzero"`
MinItems *int `json:"minItems,omitzero"`
MaxItems *int `json:"maxItems,omitzero"`
Deprecated bool `json:"deprecated,omitzero"`
}
Schema is the subset of JSON Schema 2020-12 the document uses.
type Scheme ¶
type Scheme struct {
Name string
Type string // http or apiKey
Scheme string // http: bearer
BearerFormat string // http bearer: the token's format
In string // apiKey: cookie, header or query
Param string // apiKey: the cookie's, header's or parameter's name
}
Scheme is a security scheme: Name is its key in components.securitySchemes, the rest its definition.
func Collect ¶
Collect returns the schemes of a middleware chain's layers, outermost first, without repeats: a scheme reported twice keeps its first place.
func CookieAuth ¶
CookieAuth is the scheme of a session token in the cookie named name.
type Securer ¶
type Securer interface {
OpenAPISecurity() []Scheme
}
Securer is implemented by the handler an authentication middleware returns: the schemes the middleware accepts, in order. chok collects them from each route's middleware chain into the route's security, so the document says a route is protected exactly when a middleware that authenticates runs on it. identity's Authn implements it; nothing exported does, so an application's own middleware is not recognized.