Documentation
¶
Overview ¶
Package openapi describes an app's API as an OpenAPI 3.1 document, generated from its routes: each typed handler's (web.H) input (path, query and header parameters, the JSON body, with what their validate rules say), its result and the route's status (web.Route.Status), what its middleware asks for and may answer (web.Documented: package auth's Require is a bearer token), and errors as RFC 9457 problem details.
ForApp adds the openapi command, which writes the document to a file (openapi.json) to commit beside the code, and serves it; Check, in a test, fails when the file is out of date:
// routes/api.go
var OpenAPI = openapi.Config{Title: "Shop", Version: "1.0.0", Prefix: "/api/v1", Path: "/api/v1/openapi.json"}
// main.go's setup, after the routes
if err := openapi.ForApp(app, srv, routes.OpenAPI); err != nil {
return nil, err
}
The document is built from types once, when asked for: nothing runs per request.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Check ¶
Check returns an error unless cfg.File holds r's document as Spec writes it, and the document describes every route at or below cfg.Prefix (when set): in a test, it catches a route or a type changed without the document, and a route under the prefix that isn't a typed handler. The error says how to fix it.
func ForApp ¶
ForApp adds the openapi command to app, which writes the document of srv's routes to cfg.File (or, with --check, fails if the file is out of date), and serves the document at cfg.Path if it's set. Call it after adding the routes. The command builds no app: it needs no database.
func Spec ¶
Spec returns the OpenAPI 3.1 document of r's routes, as indented JSON, and warnings about what it couldn't describe: routes that aren't typed handlers (left out), results that are a web.Responder (their bodies unknown), types with their own MarshalJSON. The same routes and Config always give the same bytes.
Types ¶
type Config ¶
type Config struct {
// Title is the API's name (info.title). Required.
Title string
// Version is the document's version (info.version), "1.0.0" if empty.
// It's the API's, not Anetos's or the app's build.
Version string
// Description introduces the API (info.description), in Markdown.
Description string
// Prefix limits the document to the routes whose path is Prefix or
// below it ("/api/v1"); "" describes every typed route.
Prefix string
// File is where the openapi command writes the document and [Check]
// reads it, relative to the working directory: "openapi.json" if
// empty.
File string
// Path, if not empty, is where [ForApp] serves the document
// ("/api/v1/openapi.json"), for clients and tools.
Path string
// Servers are the API's base URLs (servers), such as
// "https://api.example.com"; none means "/": the document's own
// host.
Servers []string
// SecuritySchemes are the security schemes that middleware may name
// (web.MiddlewareDoc.Security) besides "bearer", which is built in.
SecuritySchemes map[string]SecurityScheme
}
Config says what the document describes and where it goes.
type SecurityScheme ¶
type SecurityScheme struct {
// Type is "http" or "apiKey".
Type string `json:"type"`
// Scheme is an http scheme's name: "bearer", "basic".
Scheme string `json:"scheme,omitempty"`
// BearerFormat hints at a bearer token's format, for documentation.
BearerFormat string `json:"bearerFormat,omitempty"`
// In is where an apiKey goes: "header", "query" or "cookie".
In string `json:"in,omitempty"`
// Name is an apiKey's header, query parameter or cookie name.
Name string `json:"name,omitempty"`
// Description says how to get the credentials, in Markdown.
Description string `json:"description,omitempty"`
}
SecurityScheme is an OpenAPI security scheme.
Source Files
Directories