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