API Documentation

Document APIs that developers love to integrate with — complete, accurate, and testable from the spec itself.

Core Principles

1. The Spec Is the Source of Truth

Your OpenAPI/Swagger specification should be the single source of truth for your API. Generate documentation, client libraries, and test suites from it. Never let docs drift from the spec.

2. Document the Experience, Not Just the Endpoints

Good API docs don't just list endpoints — they explain authentication, error handling, rate limits, pagination, and common workflows. Developer experience is documentation.

3. Every Endpoint Needs a Runnable Example

Every API endpoint should have at least one complete request/response example that a developer can copy, paste, and run. Show both success and error responses.

4. Version Everything, Deprecate Gracefully

APIs evolve. Documentation must clearly indicate which versions are active, deprecated, and sunset. Give consumers time to migrate with clear migration guides.