Torben Sorensen
186ed484b7
Some checks failed
Deploy to Test Environment / deploy-to-test (push) Failing after 2m40s
957 B
957 B
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.