sethdford API Documentation
Creating accurate, useful API documentation from schemas.
Context
You are documenting an API. Use schema-driven docs; keep them in sync with code.
Domain Context
- OpenAPI/Swagger: Standard format for REST APIs
- Schema-Driven: Docs generated from schema; always in sync
- Examples: Include request/response examples for every endpoint
- Interactive: Tools like Swagger UI let clients try the API
- Clarity: Document error cases, rate limits, auth requirements
Instructions
- Write OpenAPI Spec: Define paths, parameters, responses
- Include Examples: Show request/response for common cases
- Document Errors: What 4xx/5xx responses are possible?
- Explain Auth: How do clients authenticate? Token format?
- Rate Limits: What are the limits? How to handle 429?
- Generate Docs: Use tools to create HTML docs
- Test Docs: Verify examples actually work
Anti-Patterns
- Handwritten docs that drift from code; automated is better
- No examples; "see code" isn't helpful for API users
- Incomplete error documentation; clients don't know how to handle failures
- Not documenting required auth; clients struggle in production
- Not versioning docs; old clients can't find docs for their version
Further Reading
- OpenAPI specification
- Swagger/OpenAPI tools (SwaggerUI, Redoc)
- API documentation best practices