API Documentation (OpenAPI)

Overview

Interactive HTTP API documentation for neo-backend. Doc routes are public (excluded from the auth middleware) so anyone on the VPN/internet can browse schemas without a token; protected endpoints still require Bearer auth when using Try-it-out.

Routes (no /api/v2 prefix)

These paths are registered outside the global api/v2 prefix:

URL	Purpose
/docs	Scalar API reference (primary UI)
/swagger	Swagger UI (alternate UI, persisted authorization)
/openapi.json	Raw OpenAPI 3 spec (JSON) — import into Postman, Retool, Scalar MCP
/openapi.yaml	Raw OpenAPI 3 spec (YAML) — same spec, YAML format

Example (devlab):

https://devlab.blockchainyourip.com/openapi.json
https://devlab.blockchainyourip.com/openapi.yaml
https://devlab.blockchainyourip.com/docs
https://devlab.blockchainyourip.com/swagger

Runtime API calls still go to /api/v2/... — the spec paths include that prefix.

Offline generation

npm run openapi:generate

Builds the app and runs dist/generate-openapi.js without a live MongoDB connection. Useful for CI artifacts or diffing spec changes.

Configuration

Env var	Purpose
API_PUBLIC_URL	Bare origin (no /api/v2). When set, exposed as OpenAPI servers[0] so off-origin tools (Scalar hosted MCP) know where to send requests. Example: https://devlab.blockchainyourip.com

Security schemes in spec

• bearer — standard user/API token (Authorization: Bearer …)
• platform — X-Platform-Admin-Token header for /platform/* routes (PLATFORM_ADMIN_TOKEN env)

How it works

• @nestjs/swagger CLI plugin (introspectComments) annotates DTOs from TypeScript + JSDoc
• @ApiStandardErrors() decorator mirrors GlobalExceptionFilter error envelope on documented routes
• bson/bson module-load redirect in main.ts — workaround for @nestjs/swagger + bson@6 ObjectId fields

Key files

• src/main.ts — setupApiDocs(), Scalar + Swagger mount
• src/generate-openapi.ts — offline generator
• src/app.module.ts — excludes docs, swagger, openapi.json, openapi.yaml from auth middleware
• src/shared/openapi/ — ErrorResponse, @ApiStandardErrors()
• nest-cli.json — plugin dtoFileNameSuffix includes .controller.ts / .type.ts

Known issues

• SCIM routes not yet excluded from spec generation (see README TODO)