24 lines
1.2 KiB
Markdown
24 lines
1.2 KiB
Markdown
# 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.
|