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.
51 lines
1.9 KiB
Markdown
51 lines
1.9 KiB
Markdown
# 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.
|