Contract Artifacts implemented
The portal publishes copied OpenAPI and AsyncAPI YAML artifacts so API consumers
have a stable browser-accessible location while canonical authoring remains in
doc/api.
Available Artifacts
| Artifact | Purpose | Link |
|---|---|---|
| OpenAPI draft | REST endpoint and schema contract | Download OpenAPI YAML |
| Scalar OpenAPI copy | Renderer-compatible copy generated from the REST contract | Download Scalar OpenAPI YAML |
| AsyncAPI draft | Event envelope, subjects, and payload contract | Download AsyncAPI YAML |
The docs-portal-check target syncs both files before building Docusaurus. A
build should fail if the portal copy drifts from the committed canonical
contracts.
Authoring Model
Domain teams author API fragments under doc/api/openapi/** and
doc/api/asyncapi/** as those domains migrate. The bundled draft artifacts stay
the consumer-facing contract until generated rendering is added.
Rendering Roadmap
This page is deliberately artifact-first. The next generated-reference slice should render the same synced YAML files into browsable REST and event reference pages without hand-editing endpoint or payload shapes.
Before choosing a renderer, use API Reference Rendering Options to compare Docusaurus-native OpenAPI generation, embedded viewers, and the current static artifact baseline.