API Documentation

API documentation is the contract between your service and its consumers. Incomplete or inaccurate API docs cause integration failures, support tickets, and abandoned adoption. This skill covers REST (OpenAPI), event-driven (AsyncAPI), and language-native API documentation patterns.

Review Workflow

When reviewing existing API documentation, follow this sequence:

1. Inventory endpoints — scan route handlers/controllers and cross-reference against the spec's paths. Missing endpoints are the most common defect.
2. Check required elements — for each endpoint, verify all 7 elements below (summary, description, parameters, request body, responses, examples, auth).
3. Validate examples — request/response examples should be valid JSON matching the declared schemas. Invalid examples break SDK generators and mislead consumers.
4. Audit error responses — every endpoint should document at least 400, 404 (for resource endpoints), and 500 responses. Missing error docs force consumers to discover failures at runtime.
5. Verify authentication — security schemes should be defined in components/securitySchemes and applied globally or per-endpoint.
6. Check the quality checklist at the end of this document for a final pass.

Quick Reference

For copy-paste endpoint templates, see references/endpoint-templates.md. For advanced OpenAPI patterns (discriminators, webhooks, callbacks), see references/openapi-patterns.md. For complete working specs, see examples/petstore-openapi.yaml and examples/events-asyncapi.yaml.