Swagger / OpenAPI

NOOSChain can expose development Swagger/OpenAPI documentation for the HTTP API. This is operator/developer tooling only. It is enabled by default outside production and refused in production when explicitly enabled.

Environment

Variable	Default	Meaning
NOOS_SWAGGER_ENABLED	true outside production, false in production	Enables Swagger/OpenAPI documentation.
NOOS_SWAGGER_ROUTE_PREFIX	/docs	Route prefix for the Swagger UI.
NOOS_SWAGGER_HOST	127.0.0.1	Host for a standalone Swagger server when using a separate port.
NOOS_SWAGGER_PORT	3001	Port for Swagger. If it equals the API PORT, Swagger is mounted on the API server.

The OpenAPI JSON is also served at /openapi.json on whichever server hosts Swagger.

Development examples

Run the NOOSChain API on port 3000 and Swagger on port 3001:

$env:PORT="3000"
$env:NOOS_SWAGGER_ENABLED="true"
$env:NOOS_SWAGGER_PORT="3001"
npm run dev

Open:

http://127.0.0.1:3001/docs
http://127.0.0.1:3001/openapi.json

Mount Swagger on the API server instead:

$env:PORT="3000"
$env:NOOS_SWAGGER_ENABLED="true"
$env:NOOS_SWAGGER_PORT="3000"
$env:NOOS_SWAGGER_ROUTE_PREFIX="/docs"
npm run dev

Open:

http://127.0.0.1:3000/docs
http://127.0.0.1:3000/openapi.json

Security model

Swagger documents the security boundary for each route:

• Public/system routes include shallow health and authentication entry points.
• Blockchain/domain routes expose chain, transaction, consensus-state, governance, bucket, and record APIs.
• Operator/local operations expose node-local observability, sync, peer, incident, snapshot, payload-backfill, and runtime-membership APIs. These are not public chain APIs.
• Node-to-node/internal routes are used by gossip, Raft transport, and external Raft callback plumbing.
• Development/local helpers are disabled in production.
• Operator routes use bearer auth with Authorization: Bearer <NOOS_OPERATOR_TOKEN>.
• Node-to-node routes use signed node headers: x-noos-node-id, x-noos-node-timestamp, and x-noos-node-signature.
• Protected actor routes use normal API actor authentication.
• Development-only helpers are marked as development routes and are not available in production.

The OpenAPI document describes secrets by name only. It must not include actual operator tokens, private keys, DEKs, plaintext, or encrypted payload bytes.

Production behavior

Production startup refuses:

$env:NODE_ENV="production"
$env:NOOS_SWAGGER_ENABLED="true"
npm run start

This fails closed because Swagger is development/operator documentation, not a public chain API. For production operations, use the operator CLI and the protected observability endpoints.

Documentation source

On the main API server, Swagger is generated from Fastify route schema metadata. Each route declaration should include tags, summary, description, query/body schemas where applicable, response schemas, and security metadata. Tags are category-prefixed so the generated UI separates Public/System, Blockchain/Domain API, Operator/Local Operations, Node-to-node/Internal, and Development/Local Helper endpoints.

The Swagger UI includes a small NOOSChain theme and a left navigation sidebar that links to those category-prefixed tag sections. The UI also enables request snippets and request duration display for easier operator debugging.

Shared schema definitions live under:

• src/api/schemas/common-schemas.ts
• src/api/schemas/transaction-schemas.ts
• src/api/schemas/observability-schemas.ts
• src/api/schemas/operator-schemas.ts
• src/api/schemas/route-schemas.ts

When Swagger runs on a separate documentation-only port, it serves a static OpenAPI document derived from the same route-schema registry. That server does not host the application routes, so it cannot collect route metadata directly.

New routes should be added with Fastify's route schema option and covered by npm run test:swagger, which checks that the OpenAPI document has route metadata, component schemas, and security schemes.