Documentation
¶
Overview ¶
Package openapi integrates Huma with gorbital (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 gorbital 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: stable (ADR-0015, ADR-0054).
Index ¶
Constants ¶
const BearerScheme = "bearer"
BearerScheme is the name of the bearer security scheme.
Variables ¶
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 ¶
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 a gorbital 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 gorbital 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 ¶
New returns a Huma API registered on mux. It serves the OpenAPI document at /openapi.json and /openapi.yaml (unless WithoutSpecEndpoints), disables Huma's built-in docs (use MountDocs) and response $schema links, and doesn't expose /schemas.
Call InstallErrors before registering operations.
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 Incompatibility ¶
type Incompatibility struct {
// Operation is the method and path, such as "GET /ops/settings/{key}".
Operation string
// Where locates the change inside the operation, such as
// "response 200 application/json: items[].key". Empty for the operation
// itself.
Where string
// Change says what changed, such as "removed".
Change string
}
An Incompatibility is a difference between two OpenAPI documents that can break a client written against the older one (ADR-0054).
func CheckCompatible ¶
func CheckCompatible(baseline, current []byte, prefix string) ([]Incompatibility, error)
CheckCompatible compares the operations under prefix (such as "/ops/") in a baseline OpenAPI 3 JSON document with the current one and returns every change that can break existing clients, sorted. Additions are compatible. It reports:
- a removed path or method (path parameters may be renamed);
- a removed parameter, or one that became required;
- a request body, media type or property that was removed, a property or body that became required, a request type that accepts fewer types, or an enum that allows fewer values;
- a removed response status or media type, a removed response property, one that is no longer always present, or a response type that may return types it didn't before;
- authentication required by an operation that had none.
Schemas are compared through $ref, nested objects, array items and map values. Descriptions, examples, bounds and formats aren't compared. Generated apps check /ops/* against api/openapi.baseline.json; apps can check their own API the same way.
func (Incompatibility) String ¶
func (i Incompatibility) String() string
String formats the incompatibility as one line.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
An Option configures New.
func WithBearerAuth ¶
WithBearerAuth declares the bearer security scheme used by Bearer.
func WithDescription ¶
WithDescription sets the API description shown in the docs.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package reference renders an OpenAPI 3.1 document as an API reference in the gorbital design (ADR-0049): an overview, and a page per operation with its parameters, responses, request examples in curl, Go and TypeScript, response examples and "Try it".
|
Package reference renders an OpenAPI 3.1 document as an API reference in the gorbital design (ADR-0049): an overview, and a page per operation with its parameters, responses, request examples in curl, Go and TypeScript, response examples and "Try it". |