9b1f7de05f
@netlify /reference/api/ [Preview the API reference](https://deploy-preview-26048--docsdocker.netlify.app/reference/api/) Adds a shared API reference experience for Hub, DVP, and Registry: a catalog, operation navigation, linked schemas, request and response examples, and matching HTML and Markdown output. A validation and generation pipeline prepares the reference data for Hugo and runs as part of Docker and Netlify builds. Migrates the three specifications to OpenAPI 3.2, correcting response shapes, nullable fields, and authentication and token examples. The Hub migration also corrects SCIM contracts and CSV exports; DVP gains complete report response schemas and examples. Registry keeps its documented Hub-specific subset, with authentication and media negotiation expressed through OpenAPI security and content fields. Validation is strict for both checks and generation, with no exception baseline or bypass flag. The build uses the migrated sources directly, without migration scripts or records. Page and specification URLs remain stable, including the DVP alias. Operation and schema anchors change. Engine and Governance retain their existing references. Validated locally with Go tests, strict validation of all three specifications (zero diagnostics), scoped formatting and lint, and a full Hugo build checking all 176 HTML/Markdown page pairs, example parity, reference links, and byte-identical published specifications. A browser check confirmed raw CSV rendering and the generated request header. No live API requests were made.
3.8 KiB
API reference build
This tool validates the Hub, DVP, and Registry OpenAPI sources in
content/reference/api/ and generates presentation data for Hugo. Engine and
AI Governance retain their existing sources and renderers.
Commands
Use the Go version declared in go.mod, Hugo, and the site's Node dependencies.
From the repository root:
$ npm ci
$ ./hack/api-docs/run.sh test
$ ./hack/api-docs/run.sh generate
$ hugo server
For a static build with HTML/Markdown checks, run
./hack/api-docs/run.sh build. To serve that build on port 1314, run
./hack/api-docs/run.sh serve. Set DOCS_URL and DOCS_PORT when using another
address. Run generation again after changing a specification or source manifest entry.
With docker compose watch, changes to the registered specifications or
hack/api-docs/ rebuild the server image and regenerate the reference.
Docker builds and Netlify deploy previews run generation before Hugo. Generated
data, validation reports, binaries, and local builds go under tmp/api-reference/.
Hugo reports an error if the generated data is absent.
Processor inputs
sources.json registers input specifications and their product/manual
relationships. Both generation and the validation wrapper use this manifest.
Hugo reads the generated presentation data, rather than this file. Authentication
descriptions come from the specifications and linked guides.
validation/ contains the Vacuum rules and locked official
schema resources. testdata/ contains validation fixtures. The presentation model
version and supported dialect are defined by the processor, not configurable
manifest fields.
Pipeline
- Parse the authoritative YAML with
libopenapiand preserve source values and reference identities. Verify locked OpenAPI dialect resources. - Run Vacuum policy checks and JSON Schema validation of schemas and supplied examples, followed by documentation profile checks.
- Generate presentation model version 1: operations, effective security and servers, parameters, media variants, examples, schema links, and provenance.
- Render HTML and Markdown through the content adapter and
api-docstemplates. - Run the shared site flattening script, then check generated operation, parameter, media, schema, and link coverage.
The shared hack/flatten-and-resolve.js script resolves Markdown link destinations
relative to each original file, then moves index.md files to flattened paths.
It preserves code examples and other text. API pages use the same processing as
other pages; links that already use published URLs remain unchanged.
The published YAML URLs still serve the source files directly. There is no conversion step, snapshot dependency, Node migration package, or source archive in the build.
Validation
check is strict and reports every documentation profile failure:
$ ./hack/api-docs/run.sh check
Generation runs the same strict validation. Any diagnostic fails the build;
there is no exception baseline. Reports are written to
tmp/api-reference/validation.json.
Tests and scope
Go fixtures cover dialects, references, recursion, boolean schemas, examples,
security overrides, server and parameter precedence, and request generation.
verify-output.mjs checks all generated HTML/Markdown pairs and retention of
Engine v1.40–v1.56 in ReDoc, unchanged Governance rendering, and byte-identical
published specifications. It also checks local links and fragments from API pages,
including links to docs.docker.com. The site htmltest checks include migrated
Hub, DVP, and Registry references. browser-checks.mjs exports a Playwright check for
navigation, page aliases, filtering, requests, and narrow screens.
Callbacks and webhook navigation are unsupported and fail validation. Request examples are POSIX shell templates; they do not make service calls.