ADR 0007: OpenAPI Governance and Usability Standard

Ratification

Adopted before ADR 0018. There was no separate ratification process. Git history for this file on main is the record.

• Discussion Issue: not recorded (before ADR 0018)
• Merge PR: see git history for this file
• Accepted: as merged to main

Context

Why this matters: OpenAPI is not only a human-readable page — it is the contract that clients and tests use. Thin examples, missing error shapes, and missing headers push integrators to read code or guess. That does not scale and costs support time.

We already had docs; the gap was quality and consistency: full validation examples, links between related operations, snapshot tests so the contract cannot drift quietly, and CI that treats the spec like application code.

Decision

We use an OpenAPI governance standard: strict operation metadata, complete examples for errors and writes, response links where workflows exist, and automated contract checks in the pipeline.

Scope

• In scope: OpenAPI schema quality, endpoint docs usability, examples, links, response contracts, CI checks.
• Out of scope: Public API monetization policies, external developer portal platform migration.

Alternatives considered

1. Keep current docs and improve ad-hoc.
   • Pros: no process overhead.
   • Cons: quality drifts over time; no consistent consumer experience.
2. Adopt strict OpenAPI governance baseline (selected).
   • Pros: predictable contracts, safer integrations, easier onboarding, scalable docs maintenance.
   • Cons: requires discipline and CI investment.

Consequences

Positive

• Swagger becomes actionable: clear workflows, realistic examples, and stable response semantics.
• Higher confidence for integrators and lower support load.
• Breaking changes become detectable early via contract checks.

Trade-offs

• More up-front effort per endpoint (examples, links, operation metadata).
• Need to keep CI checks and governance rules current.

Standard requirements

• Every operation has stable operationId, clear summary, and response model.
• Validation errors use stable code/key envelopes with complete examples for all mapped rules.
• Write operations document idempotency behavior and conflict semantics.
• Where workflow exists, response links guide client to the next operation.
• Key operations include code samples (curl minimum; optional additional languages).
• Error responses include documented headers when relevant (for example rate-limit headers).
• Deprecation must use explicit OpenAPI markers and migration guidance.
• Snapshot contract tests are required to detect accidental changes in fields, error codes, and schema types.

Implementation plan

1. Phase 1 (implemented): improve user endpoints with complete 422 examples, links, operation IDs, code samples, and read-after-write flow.
2. Phase 2: add shared components.responses and reusable error definitions across routers.
3. Phase 3: enforce OpenAPI linting (Spectral) and contract diff checks in CI/pre-deploy gates.
4. Phase 3.1 (implemented): add strict snapshot contract test against accepted OpenAPI baseline.
5. Phase 4: expand code samples and external docs links for operational recovery/runbooks.

Validation

• Technical checks: make type-check, make test, make contract-test, make docs-fix.
• Operational checks: manual Swagger walkthrough for create/get workflow, 4xx/422/429 examples and links.
• Documentation updates: ADR index and generated handbook table via docs sync pipeline.

References

• Related ADRs:
  0003-error-contract-governance
0004-api-versioning-policy
0005-api-security-defaults
0006-idempotency-write-operations
• Related runbooks:
  0006-api-security-failing
0007-openapi-contract-test-failing

Page history