Torben Sorensen
d004efb84b
All checks were successful
Deploy to Test Environment / deploy-to-test (push) Successful in 16m21s
19 lines
957 B
Markdown
19 lines
957 B
Markdown
# ADR-018: API Documentation Strategy
|
|
|
|
**Date**: 2025-12-12
|
|
|
|
**Status**: Proposed
|
|
|
|
## Context
|
|
|
|
As the API grows, it becomes increasingly difficult for frontend developers and other consumers to understand its endpoints, request formats, and response structures. There is no single source of truth for API documentation.
|
|
|
|
## Decision
|
|
|
|
We will adopt **OpenAPI (Swagger)** for API documentation. We will use tools (e.g., JSDoc annotations with `swagger-jsdoc`) to generate an `openapi.json` specification directly from the route handler source code. This specification will be served via a UI like Swagger UI for interactive exploration.
|
|
|
|
## Consequences
|
|
|
|
* **Positive**: Creates a single source of truth for API documentation that stays in sync with the code. Enables auto-generation of client SDKs and simplifies testing.
|
|
* **Negative**: Requires developers to maintain JSDoc annotations on all routes. Adds a build step and new dependencies to the project.
|