Maintaining documentation¶
Tooling¶
Documentation uses MkDocs with the Material theme. Versions of the docs tools and OpenAPI validator are pinned in requirements-docs.txt; they are separate from the Node application dependencies.
From the repository root:
Open http://127.0.0.1:8000/. MkDocs reloads as Markdown and configuration change.
Verify before publishing¶
uv run --no-project mkdocs build --strict
uv run --no-project openapi-spec-validator docs/api/openapi.yaml
The build writes static output to ignored site/. Publish the entire directory to your chosen static host so the Swagger HTML and OpenAPI YAML are included. There is no docs publishing workflow configured, and the backend container does not serve the site. Swagger's CDN assets require internet access; all other pages and the raw contract are static.
Keep documentation accurate¶
When changing src/server.js:
- Update endpoint methods, request/response schemas, status codes, and examples in
docs/api/openapi.yaml. - Update the API guide and any affected setup, configuration, or concept pages.
- If
package.jsonchanges version, keep the OpenAPIinfo.versionaligned when maintaining the contract. The release workflow does not update the specification automatically. - Run strict build and schema validation, then smoke-test Swagger against a disposable local backend.
Navigation is declared in mkdocs.yml. The Swagger page embeds docs/api/swagger-ui.html; that HTML loads its sibling openapi.yaml using a relative URL so static hosting under a subpath works.
Schema validation checks the contract's structure, not whether the implementation matches it. Review against the actual routes and test real responses when updating the API.