OpenAPI Tooling

Use this guide when linting or previewing the OpenAPI specification.

The source of truth is openapi/openapi.yaml. Run commands from the repository root inside nix develop so just and redocly are available.

Commands

• just lint-spec bundles the OpenAPI spec with Redocly and lints it with Spectral.
• just swagger-serve previews Swagger UI on port 9080.
• just redoc-serve previews Redoc on port 9081.

Tooling

lint-spec uses Redocly from Nix to bundle the spec, then runs Spectral in Docker.

redoc-serve uses Redocly from Nix:

just redoc-serve

swagger-serve uses Docker so Swagger UI does not need to be installed locally:

just swagger-serve

Override preview ports by passing just variables:

just REDOC_PORT=9091 redoc-serve
just SWAGGER_PORT=9090 swagger-serve