- feat: internal/api/openapi/openapi.yaml describes every operation (OpenAPI 3.0.3), written by hand and embedded in the binary; GET /api/v1/openapi.yaml serves it - feat: GET /api/docs/ serves Swagger UI from assets embedded in the binary (github.com/swaggest/swgui, v5emb), so opening it never contacts another server; both are public because they contain no data - feat: response objects in the spec are closed (additionalProperties: false) - test: the spec is valid OpenAPI; the router and the spec describe the same operations in both directions; every operation has an id, a summary, a tag, a documented 401 when it needs a token and a 403 when it is admin only - test: a contract test drives every operation through the real services, including a real scan and real streaming, and validates each response (status, headers, JSON body) against the spec with kin-openapi; it fails if an operation was never exercised. Checked by breaking the code and the spec on purpose - test: the docs page loads without any external address and every asset it references is served - docs: README section on the interactive documentation and on keeping the spec in step with the code Closes #15
13 lines
372 B
Go
13 lines
372 B
Go
// Package openapi holds the OpenAPI description of the Sonda API.
|
|
//
|
|
// The spec is written by hand and embedded in the binary. Tests keep it honest:
|
|
// they fail when a route and the spec disagree, and they validate real
|
|
// responses against it.
|
|
package openapi
|
|
|
|
import _ "embed"
|
|
|
|
// Spec is the OpenAPI 3.0 document, in YAML.
|
|
//
|
|
//go:embed openapi.yaml
|
|
var Spec []byte
|