ADR 0003: API documentation & OpenAPI strategy

Status: Accepted
Date: 2025-10-18

Context

The API surface is large and cross-cutting (multiple domains, modules, and authentication flows). We need:

• A single source of truth for request/response shapes
• Tooling for Postman collections, TypeScript types, and client SDKs
• Concise, conceptual VitePress docs that don't duplicate every field and response

Maintaining endpoint details separately in Markdown and Postman leads to drift and duplicated effort.

Decision

Use OpenAPI 3.1 as the canonical API contract and generate everything else from it:

• Author modular specs under openapi/ (per domain/module) and bundle into openapi/openapi.yaml
• Use the bundled spec as the source for:
  • Interactive API reference at /api/ (via VitePress + OpenAPI integration)
  • Postman collections (via GitHub integration)
  • Generated TypeScript types and other SDKs
• Keep VitePress guides conceptual and task-focused:
  • Explain flows, usage patterns, and examples
  • Link to the API reference (e.g. /api/#tag/public-listings) instead of re-stating schemas

Consequences

Positive

• OpenAPI spec becomes the single source of truth for the API
• Less duplication between docs, Postman, and client code
• Easier to onboard: developers can browse high-level guides then drill into /api/ for details
• Better fit for contract-first or contract-aware development

Negative / trade-offs

• Requires discipline: new or changed endpoints must be reflected in OpenAPI, not only in code
• Some documentation work moves from Markdown into YAML (OpenAPI)
• Developers need basic familiarity with OpenAPI structure

Related documentation

• API Documentation guide
• OpenAPI Integration guide
• Module System Guide