17. Documentation
17. Documentation
An undocumented API is an unusable API. Good documentation is not an afterthought — it is a deliverable that ships alongside the code.
Use OpenAPI as Your Source of Truth
The OpenAPI Specification (formerly Swagger) is the industry standard for describing REST APIs. Maintain an OpenAPI spec file (openapi.yaml or openapi.json) in your repository and treat it as the single authoritative description of your API. Tools like Swagger UI, Redoc, and Stoplight can render it into interactive documentation automatically.
What Every Endpoint Needs
Each endpoint in your spec should include:
- A clear description of what the endpoint does and when a client should use it.
- All request parameters — path parameters, query parameters, headers, and the request body schema — with types, constraints, and defaults.
- A successful response example showing the exact JSON shape a client will receive.
- Error response examples for every error code the endpoint can return (400, 401, 404, 422, etc.), using your standard error envelope.
Keep the Spec in Sync
Documentation that drifts out of sync with the code is worse than no documentation at all — it actively misleads developers. Update the spec as part of your development workflow, not as a separate task after the fact. Consider:
- Generating the spec from code annotations where your framework supports it (Laravel has packages for this; FastAPI does it natively).
- Validating responses against the spec in your test suite so that any drift is caught before it ships.
- Reviewing the spec as part of your pull request checklist.
Provide a Changelog
Maintain a changelog that records every version of your API, the changes it introduced, and any migration steps required. This is especially important when you deprecate or remove endpoints — consumers need to know what changed and how to adapt.