openapi

package
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 10 Imported by: 0

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

View Source
var BearerAuth = Scheme{Name: "bearerAuth", Type: "http", Scheme: "bearer", BearerFormat: "JWT"}

BearerAuth is the scheme of a JWT in the Authorization header.

Functions

func Build

func Build(in Info, ops []Operation) ([]byte, error)

Build renders the document for ops.

func Summary

func Summary(method, path string, list bool) string

Summary derives a route summary: "Create post", "Get post", "List posts", "Replace post", "Update post", "Delete post". A POST to a segment that is not a plural collection is named after the segment: POST /auth/refresh-token is "Refresh token".

func UI

func UI(title, specURL string) string

UI is the /docs page: Swagger UI from its CDN, pointed at specURL.

Types

type Info

type Info struct {
	Title   string
	Version string
}

Info is the document-level metadata.

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

func Collect(layers ...[]Scheme) []Scheme

Collect returns the schemes of a middleware chain's layers, outermost first, without repeats: a scheme reported twice keeps its first place.

func CookieAuth

func CookieAuth(name string) Scheme

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL