1.2 KiB
1.2 KiB
ADR 0003: REST API with Swagger Documentation
Date: 2026-04-26 Status: Accepted
Context
The API must be understandable and testable without reading source code. Two documentation approaches were considered:
- OpenAPI/Swagger — industry standard, generates interactive UI, supports code generation.
- Postman collection — already present (
tests/adastra-api-tests.postman_collection.json), good for integration testing but not a substitute for living documentation.
Decision
Use swagger-jsdoc + swagger-ui-express to generate and serve an interactive OpenAPI 3.0 documentation at a dedicated route. Annotations are written as JSDoc comments directly in route/controller files.
Postman collections are kept for integration/regression testing (run via npm run test:postman with Newman), complementing rather than replacing Swagger.
Consequences
- Positive: Living documentation — always in sync with the code.
- Positive: Interactive UI allows manual endpoint testing without a separate tool.
- Positive: OpenAPI spec can be used to generate client types if needed.
- Negative: JSDoc annotations add verbosity to route files. Annotations must be kept up to date manually.