Skip to main content

OpenAPI

This page is not the endpoint catalog

Do not add hand-written request and response tables here. They will drift from the DTOs.

Where Swagger is mounted​

src/swagger.ts calls SwaggerModule.setup with doc.prefix (default docs) when APP_ENV is not production. The log line is Swagger documentation available at /{prefix}.

The setup options that were read do not set a custom jsonDocumentUrl. Nest’s default JSON route for that setup is /{prefix}-json, which is /docs-json when the prefix is docs.

Confirm on a running non-production API before a CI job depends on the path. This pass did not HTTP-GET the document.

How to integrate it into this site​

NestJS API (APP_ENV is not production)
        |
        v
GET /docs-json    # confirm this path
        |
        v
Commit the spec under static/openapi/ or fetch it in CI
        |
        v
Render with an OpenAPI plugin or a static Redoc page

Recommended steps when you wire it:

  1. Boot the API with the local env from Local development.
  2. Download the JSON from the confirmed path.
  3. Add a Docusaurus plugin that renders that file. Do not paste operations into Markdown.
  4. Rebuild this site.

Until that plugin is added, use the running API’s Swagger UI at /docs.

What this site still owns​

Side effects, state machines, tenancy, and failure behavior are not fully visible in OpenAPI. Those stay in the domain and architecture pages. If a Swagger description and a domain page disagree about a side effect, trust the code and fix the description.