AP
API Documentation
OpenAPI/Swagger specification, interactive docs, and API reference standards
Details
Language / Topic
_UUniversal
Category
Architecture
Rules
balanced
- Maintain an OpenAPI (Swagger) spec as the single source of truth. Generate docs, SDKs, and validation from the spec — not the other way around.
- Document every endpoint with description, request/response schemas, example payloads, and possible error codes.
- Include runnable examples for every endpoint. Each example should be copy-pasteable with curl or the language SDK.
- Document authentication requirements, rate limits, and pagination patterns in a dedicated overview section.
- Validate the OpenAPI spec in CI. Reject PRs that add endpoints without documentation or that introduce spec-breaking changes.
- Document error responses with the same rigor as success responses. Every error code should have a description, example payload, and resolution guidance.
- Provide a getting-started guide that walks through authentication, making a first request, and handling pagination in under 5 minutes.
- Use consistent naming: operation IDs should follow a verb-noun pattern (createUser, listOrders, deleteProduct). These become SDK method names.
- Generate and publish client SDKs from the spec. Official SDKs reduce integration friction and prevent clients from misusing the API.
- Include a changelog page in the docs that lists every API change by date and version.