diegosouzapw API Documenter
Purpose
Provides expertise in creating clear, accurate, and developer-friendly API documentation. Specializes in OpenAPI 3.x specifications, GraphQL schema documentation, and interactive API references.
When to Use
- Writing OpenAPI/Swagger specifications
- Documenting REST API endpoints
- Creating GraphQL schema documentation
- Building interactive API references
- Writing API getting-started guides
- Documenting authentication flows
- Creating SDK usage examples
Quick Start
Invoke this skill when:
- Writing OpenAPI/Swagger specifications
- Documenting REST API endpoints
- Creating GraphQL schema documentation
- Building interactive API references
- Writing SDK usage examples
Do NOT invoke when:
- Designing API architecture (use api-designer)
- Writing user-facing product docs (use technical-writer)
- Creating internal system docs (use document-writer)
- Building the actual API (use backend developer skills)
Decision Framework
Documentation Type:
├── New API → OpenAPI spec first, then guides
├── Existing API → Audit endpoints, generate spec
├── GraphQL → Schema docs + query examples
├── SDK/Library → Code samples + quickstart
└── Microservices → Service catalog + contracts
Core Workflows
1. OpenAPI Specification Creation
- Inventory all endpoints and methods
- Define request/response schemas
- Document parameters and headers
- Add authentication requirements
- Include example requests/responses
- Validate spec with linting tools
2. API Reference Documentation
- Group endpoints by resource or domain
- Write clear endpoint descriptions
- Document all parameters with types
- Provide request/response examples
- Include error codes and handling
- Add authentication examples
3. API Getting Started Guide
- Explain authentication setup
- Show first API call example
- Walk through common use cases
- Include SDK installation steps
- Provide troubleshooting tips
- Link to full reference docs
Best Practices
- Use consistent terminology across all docs
- Provide copy-pasteable code examples
- Include both success and error responses
- Version documentation with API versions
- Test all code examples before publishing
- Add rate limiting and quota information
Anti-Patterns
| Anti-Pattern | Problem | Correct Approach |
|---|---|---|
| No examples | Developers guess at usage | Include request/response examples |
| Outdated docs | Breaks developer trust | Automate doc generation from code |
| Missing errors | Surprise failures in production | Document all error codes |
| Jargon-heavy | Confuses new developers | Use clear, simple language |
| No versioning | Breaking changes unclear | Version docs with API |