Api Documentation

---
name: Api Documentation
description: Use when building API reference documentation with OpenAPI/Swagger, Redoc, and interactive examples including versioning and change tracking.
category: Developer Experience
version: 1.0.0
tools: []
---

# API Documentation

Reference documentation for APIs using OpenAPI 3.x specifications.

## Key Steps

1. Audit the API surface: examine route handlers, middleware, validators, and response serializers to identify all endpoints, HTTP methods, path/query parameters, request bodies, and response shapes.
2. Write OpenAPI 3.x specification: declare complete schema definitions with required fields, data types (format: date-time, email, uuid), enum values, and nullable vs optional fields distinguished.
3. Document response codes: every endpoint must document all status codes it can return including error responses (400, 401, 403, 404, 409, 429, 500) with exact error body schema and example payloads.
4. Create request/response examples: cover common case, edge cases, and error cases for each endpoint using realistic data.
5. Write authentication documentation: token acquisition flow, header format, refresh procedure, scope requirements per endpoint, exact error responses for expired/invalid/insufficient tokens.
6. Organize into logical groups: use tags by domain resource with descriptions of resource lifecycle (create, read, update, delete) and relationships to other resources.
7. Document pagination/filtering/sorting: consistent parameter naming across all list endpoints with cursor-based pagination, field-level filtering syntax, sort direction examples.
8. Write integration quickstarts: walk developers from zero to first successful API call in under five minutes covering auth setup, making requests with curl, interpreting responses.
9. Maintain API versioning: separate OpenAPI specifications per version with changelog describing additions, deprecations, and breaking changes.
10. Implement validation: run OpenAPI specification through Spectral linter; verify examples match schemas; compare spec against integration tests to detect undocumented endpoints.

## Standards

- Every endpoint: summary (one line), description (detailed), at least one request/response example.
- Schema descriptions: explain business meaning not just data type. Example: "The UTC timestamp when the user last authenticated" not "a date."
- Error schemas: consistent across endpoints using standard envelope with code, message, details fields.
- Deprecated endpoints: mark with deprecated flag, include migration steps and replacement endpoint reference.
- Query parameters: document default values explicitly in description and schema.
- Rate limiting: specify limit, window, and headers returned (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset).
- Validation: OpenAPI specification must pass Spectral linting with zero errors and zero warnings before publication.