Background
API documentation has been set up ad-hoc on projects like BCAN, but often not at all. Having Swagger pre-configured in scaffolding gives new developers immediate visibility into available endpoints without reading controller code, and is especially useful during client handoffs.
Tasks
In apps/backend/src/main.ts, add Swagger initialization gated behind a SWAGGER_ENABLED=true env var check:
-
DocumentBuilder config with .setTitle(), .setDescription(), .setVersion('1.0'), and .addBearerAuth() using placeholder values the TL should update for their project
-
SwaggerModule.createDocument() and SwaggerModule.setup('api', app, documentFactory) so docs are served at /api
-
Add SWAGGER_ENABLED to .example.env with a comment indicating it should only be set to true in local and staging environments, not production
-
Add a README.md note or inline comments documenting the common decorators TLs should use as they build out controllers and DTOs
Acceptance Criteria
Navigating to http://localhost:3000/api shows the Swagger UI when SWAGGER_ENABLED=true. With the env var unset or false the route does not exist. The DocumentBuilder placeholder values are clearly marked for the TL to update.
Background
API documentation has been set up ad-hoc on projects like BCAN, but often not at all. Having Swagger pre-configured in scaffolding gives new developers immediate visibility into available endpoints without reading controller code, and is especially useful during client handoffs.
Tasks
In
apps/backend/src/main.ts, add Swagger initialization gated behind aSWAGGER_ENABLED=trueenv var check:DocumentBuilder config with
.setTitle(),.setDescription(),.setVersion('1.0'), and.addBearerAuth()using placeholder values the TL should update for their projectSwaggerModule.createDocument()andSwaggerModule.setup('api', app, documentFactory)so docs are served at/apiAdd
SWAGGER_ENABLEDto.example.envwith a comment indicating it should only be set to true in local and staging environments, not productionAdd a
README.mdnote or inline comments documenting the common decorators TLs should use as they build out controllers and DTOsAcceptance Criteria
Navigating to
http://localhost:3000/apishows the Swagger UI whenSWAGGER_ENABLED=true. With the env var unset or false the route does not exist. TheDocumentBuilderplaceholder values are clearly marked for the TL to update.