Skip to main content
Version: 1.1.0

API Documentation (Scalar + Swagger UI)

Version: 1.1.0 Date: 2026-07-15

Goal: Expose the neo-backend HTTP API as browsable, interactive documentation so developers (and AI agents) can discover routes, read schemas, paste a Bearer token, and fire real requests.

Solution: Code-first OpenAPI via @nestjs/swagger (CLI plugin with introspectComments). Scalar on /docs, Swagger UI on /swagger. Raw spec at /openapi.json and /openapi.yaml (no /api/v2 prefix, no auth). Doc routes excluded from auth middleware.

Features:

  • /docs — Scalar UI; /swagger — Swagger UI (persisted authorization)
  • /openapi.json, /openapi.yaml — raw OpenAPI 3 export (Postman, Retool, Scalar MCP)
  • Bearer token authentication preselected; global security requirement on all protected routes
  • @ApiStandardErrors() — every documented route declares 400/401/403/404/500 with real ErrorResponse envelope
  • Typed 2xx responses on flagship document endpoints (were empty 200 before)
  • npm run openapi:generate — offline dump without live DB
  • API_PUBLIC_URL — absolute servers entry for off-origin consumers (Scalar hosted MCP)

Implementation Details:

  • Plugin dtoFileNameSuffix extended to .controller.ts / .type.ts so inline DTOs get schemas
  • @IsOptional() fields marked optional in TS (?) — plugin derives required from optionality, not class-validator
  • bson/bson module-load redirect in main.ts for @nestjs/swagger + bson@6 ObjectId fields
  • normalizeObjectIdSchema() — 24-hex string instead of empty object in spec
  • Removed hardcoded addServer('/api/v2') that double-prefixed Try-it-out requests
  • Object-array DTO fields (targetAutoAttributes) expose {code, value} item schemas (Scalar MCP strict clients)

Files Modified:

  • package.json / package-lock.json - @nestjs/swagger, @scalar/nestjs-api-reference
  • nest-cli.json - Swagger CLI plugin + extended suffix scan
  • src/main.ts - Spec build, Scalar/Swagger mount, Bearer security, bson redirect
  • src/generate-openapi.ts - Offline generator with matching server entry (new)
  • src/app.module.ts - Exclude /docs, /swagger, /openapi.* from auth middleware
  • src/shared/openapi/error-response.dto.ts - Shared error schema (new)
  • src/shared/openapi/api-standard-errors.decorator.ts - @ApiStandardErrors() (new)
  • src/domains/document/document.responses.ts - Document response models (new)
  • src/domains/document/document.controller.ts - Typed responses + query params
  • src/domains/stat/stat.controller.ts - Typed @Query/@Param
  • src/domains/platform/*/*.controller.ts - Standard errors on platform surface
  • .env.example - API_PUBLIC_URL, PROOF_WATCHER_ENABLED
  • README.md - Docs setup and annotation gotchas

Release fragment: feat-api-docs-swagger-scalar