| name | generating-api-docs |
| version | 1.0.0 |
| description | Create comprehensive API documentation with examples, authentication guides, and SDKs.
Use when creating comprehensive API documentation.
Trigger with phrases like "generate API docs", "create API documentation", or "document the API".
|
| allowed-tools | Read, Write, Edit, Grep, Glob, Bash(api:docs-*) |
| license | MIT |
Prerequisites
Before using this skill, ensure you have:
- API design specifications or requirements documented
- Development environment with necessary frameworks installed
- Database or backend services accessible for integration
- Authentication and authorization strategies defined
- Testing tools and environments configured
Instructions
Step 1: Design API Structure
Plan the API architecture and endpoints:
- Use Read tool to examine existing API specifications from {baseDir}/api-specs/
- Define resource models, endpoints, and HTTP methods
- Document request/response schemas and data types
- Identify authentication and authorization requirements
- Plan error handling and validation strategies
Step 2: Implement API Components
Build the API implementation:
- Generate boilerplate code using Bash(api:docs-*) with framework scaffolding
- Implement endpoint handlers with business logic
- Add input validation and schema enforcement
- Integrate authentication and authorization middleware
- Configure database connections and ORM models
Step 3: Add API Features
Enhance with production-ready capabilities:
- Implement rate limiting and throttling policies
- Add request/response logging with correlation IDs
- Configure error handling with standardized responses
- Set up health check and monitoring endpoints
- Enable CORS and security headers
Step 4: Test and Document
Validate API functionality:
- Write integration tests covering all endpoints
- Generate OpenAPI/Swagger documentation automatically
- Create usage examples and authentication guides
- Test with various HTTP clients (curl, Postman, REST Client)
- Perform load testing to validate performance targets
Output
The skill generates production-ready API artifacts:
API Implementation
Generated code structure:
{baseDir}/src/routes/ - Endpoint route definitions{baseDir}/src/controllers/ - Business logic handlers{baseDir}/src/models/ - Data models and schemas{baseDir}/src/middleware/ - Authentication, validation, logging{baseDir}/src/config/ - Configuration and environment variables
API Documentation
Comprehensive API docs including:
- OpenAPI 3.0 specification with complete endpoint definitions
- Authentication and authorization flow diagrams
- Request/response examples for all endpoints
- Error code reference with troubleshooting guidance
- SDK generation instructions for multiple languages
Testing Artifacts
Complete test suite:
- Unit tests for individual controller functions
- Integration tests for end-to-end API workflows
- Load test scripts for performance validation
- Mock data generators for realistic testing
- Postman/Insomnia collection for manual testing
Configuration Files
Production-ready configs:
- Environment variable templates (.env.example)
- Database migration scripts
- Docker Compose for local development
- CI/CD pipeline configuration
- Monitoring and alerting setup
Error Handling
Common issues and solutions:
Schema Validation Failures
- Error: Request body does not match expected schema
- Solution: Add detailed validation error messages; provide schema documentation; implement request sanitization
Authentication Errors
- Error: Invalid or expired authentication tokens
- Solution: Implement proper token refresh flows; add clear error messages indicating auth failure reason; document token lifecycle
Rate Limit Exceeded
- Error: API consumer exceeded allowed request rate
- Solution: Return 429 status with Retry-After header; implement exponential backoff guidance; provide rate limit info in response headers
Database Connection Issues
- Error: Cannot connect to database or query timeout
- Solution: Implement connection pooling; add health checks; configure proper timeouts; implement circuit breaker pattern for resilience
Resources
API Development Frameworks
- Express.js and Fastify for Node.js APIs
- Flask and FastAPI for Python APIs
- Spring Boot for Java APIs
- Gin and Echo for Go APIs
API Standards and Best Practices
- OpenAPI Specification 3.0+ for API documentation
- JSON:API specification for RESTful API conventions
- OAuth 2.0 and OpenID Connect for authentication
- HTTP/2 and HTTP/3 for performance optimization
Testing and Monitoring Tools
- Postman and Insomnia for API testing
- Swagger UI for interactive API documentation
- Artillery and k6 for load testing
- Prometheus and Grafana for monitoring
Security Best Practices
- OWASP API Security Top 10 guidelines
- JWT best practices for token-based auth
- Rate limiting strategies to prevent abuse
- Input validation and sanitization techniques
