modules/openapi

Package openapi integrates Huma with apistock (ADR-0027): an API on the standard http.ServeMux, problem+json errors produced by the application's error mapper, an API reference at /docs in the apistock design (ADR-0049, rendered by package reference), and OpenAPI export.

Huma is used only in delivery layers and the composition root of generated apps; domain, use case and repository code never imports it.

Stability: pre-1.0 (ADR-0015).

Constants#

const BearerScheme#

const BearerScheme = "bearer"

BearerScheme is the name of the bearer security scheme.

Variables#

var Bearer#

var Bearer = []map[string][]string{{BearerScheme: {}}}

Bearer is the security requirement for operations that need a session token. Use it as huma.Operation.Security.

Functions#

func InstallErrors#

func InstallErrors(mapper *httpx.Mapper)

InstallErrors makes every Huma error an httpx.Problem:

• errors matched by mapper (domain sentinels, *httpx.Problem) use their mapping;
• validation and other client errors keep their status, get the default code (for example "validation_failed") and list field errors without echoing submitted values;
• server errors become a generic 500 and are logged once by mapper.

Huma stores these hooks in package-level variables, so call InstallErrors once, from the composition root, before registering operations. It is the only package-level state an apistock app changes (ADR-0027).

func MountDocs#

func MountDocs(mux *http.ServeMux, opts DocsOptions)

MountDocs serves an API reference for the API on mux at opts.Path, in the apistock design (ADR-0049): an overview, a page per operation with its parameters, responses, request examples and "Try it", and search.

The pages are rendered from the OpenAPI document that mux serves at opts.SpecURL, read in-process on the first request, so every operation registered before the server starts appears without further setup. Styles, scripts and fonts are served by the app itself under reference.ContentSecurityPolicy; the pages make no external requests.

func New#

func New(mux *http.ServeMux, title, version string, opts ...Option) huma.API

New returns a Huma API registered on mux. It serves the OpenAPI document at /openapi.json and /openapi.yaml, disables Huma's built-in docs (use MountDocs) and response $schema links, and doesn't expose /schemas.

Call InstallErrors before registering operations.

func WriteSpec#

func WriteSpec(w io.Writer, api huma.API) error

WriteSpec writes api's OpenAPI document to w as indented JSON. Generated apps call it from "my-api openapi" to export api/openapi.json.

Types#

type DocsOptions#

type DocsOptions struct {
	Path    string // default "/docs"
	SpecURL string // default "/openapi.json", served by the same mux
	Title   string // default "API Reference"
}

DocsOptions configure MountDocs.

type Option#

type Option interface {
	// contains filtered or unexported methods
}

An Option configures New.

func WithBearerAuth#

func WithBearerAuth(description string) Option

WithBearerAuth declares the bearer security scheme used by Bearer.

func WithDescription#

func WithDescription(markdown string) Option

WithDescription sets the API description shown in the docs.