# 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.