julien
a9ef4cf629
Rewrites all 7 backend ADRs from a custom structure to the MADR 2.1.2 template required by the VS Code ADR Manager extension: bullet metadata (Status/Date), standardised section headings, "Chosen option: X, because Y" wording, and explicit Pros/Cons blocks per option.
1.9 KiB
1.9 KiB
Document the REST API with OpenAPI/Swagger
- Status: accepted
- Date: 2026-04-26
Context and Problem Statement
The API must be understandable and testable without reading source code. How should the API be documented?
Considered Options
- OpenAPI/Swagger (
swagger-jsdoc+swagger-ui-express) - Postman collection only
- No documentation
Decision Outcome
Chosen option: "OpenAPI/Swagger", because it generates living, interactive documentation directly from the source code, eliminating the risk of documentation drift.
swagger-jsdoc + swagger-ui-express generate and serve an interactive OpenAPI 3.0 UI at a dedicated route. Annotations are written as JSDoc comments directly in route/controller files. The existing Postman collection (tests/adastra-api-tests.postman_collection.json) is kept for integration and regression testing via Newman (npm run test:postman), complementing rather than replacing Swagger.
Positive Consequences
- Living documentation — always in sync with the code.
- Interactive UI allows manual endpoint testing without a separate tool.
- OpenAPI spec can be used to generate client types if needed.
Negative Consequences
- JSDoc annotations add verbosity to route files.
- Annotations must be kept up to date manually — stale annotations are possible if discipline slips.
Pros and Cons of the Options
OpenAPI/Swagger
- Good, because interactive UI — testable in the browser without Postman.
- Good, because spec is co-located with the code it describes.
- Bad, because requires discipline to keep annotations accurate.
Postman collection only
- Good, because already present; useful for regression testing.
- Bad, because not suitable as primary documentation — requires Postman to view.
- Bad, because collection and code can diverge silently.
No documentation
- Good, because zero maintenance overhead.
- Bad, because API is opaque without reading the source.