Api Documentation Generator

# API Documentation Generator ## Overview Automatically generate clear, comprehensive API documentation from your codebase. This skill helps you create professional documentation that includes endpoint descriptions, request/response examples, authentication details, error handling, and usage guidelines. Perfect for REST APIs, GraphQL APIs, and WebSocket APIs. ## When to Use This Skill - Use when you need to document a new API - Use when updating existing API documentation - Use when your API lacks clear documentation - Use when onboarding new developers to your API - Use when preparing API documentation for external users - Use when creating OpenAPI/Swagger specifications ## How It Works ### Step 1: Analyze the API Structure First, I'll examine your API codebase to understand: - Available endpoints and routes - HTTP methods (GET, POST, PUT, DELETE, etc.) - Request parameters and body structure - Response formats and status codes - Authentication and authorization requirements - Error handling patterns ### Step 2: Generate Endpoint Documentation For each endpoint, I'll create documentation including: **Endpoint Details:** - HTTP method and URL path - Brief description of what it does - Authentication requirements - Rate limiting information (if applicable) **Request Specification:** - Path parameters - Query parameters - Request headers - Request body schema (with types and validation rules) **Response Specification:** - Success response (status code + body structure) - Error responses (all possible error codes) - Response headers **Code Examples:** - cURL command - JavaScript/TypeScript (fetch/axios) - Python (requests) - Other languages as needed ### Step 3: Add Usage Guidelines I'll include: - Getting started guide - Authentication setup - Common use cases - Best practices - Rate limiting details - Pagination patterns - Filtering and sorting options ### Step 4: Document Error Handling Clear error documentation including: - All possible error codes - Error message formats - Troubleshooting guide - Common error scenarios and solutions ### Step 5: Create Interactive Examples Where possible, I'll provide: - Postman collection - OpenAPI/Swagger specification - Interactive code examples - Sample responses ## Examples ### Example 1: REST API Endpoint Documentation ```markdown ## Create User Creates a new user account. **Endpoint:** `POST /api/v1/users` **Authentication:** Required (Bearer token) **Request Body:** ```json { "email": "[email protected]", // Required: Valid email address "password": "SecurePass123!", // Required: Min 8 chars, 1 uppercase, 1 number "name": "John Doe", // Required: 2-50 characters "role": "user" // Optional: "user" or "admin" (default: "user") } ``` **Success Response (201 Created):** ```json { "id": "usr_1234567890", "email": "[email protected]", "name": "John Doe", "role": "user", "createdAt": "2026-01-20T10:30:00Z", "emailVerified": false } ``` **Error Responses:** - `400 Bad Request` - Invalid input data ```json { "error": "VALIDATION_ERROR", "message": "Invalid email format", "field": "email" } ``` - `409 Conflict` - Email already exists ```json { "error": "EMAIL_EXISTS", "message": "An account with this email already exists" } ``` - `401 Unauthorized` - Missing or invalid authentication token **Example Request (cURL):** ```bash curl -X POST https://api.example.com/api/v1/users -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{ "email": "[email protected]", "password": "SecurePass123!", "name": "John Doe" }' ``` **Example Request (JavaScript):** ```javascript const response = await fetch('https://api.example.com/api/v1/users', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ email: '[email protected]', password: 'SecurePass123!', name: 'John Doe' }) }); const user = await response.json(); console.log(user); ``` **Example Request (Python):** ```python import requests response = requests.post( 'https://api.example.com/api/v1/users', headers={ 'Authorization': f'Bearer {token}', 'Content-Type': 'application/json' }, json={ 'email': '[email protected]', 'password': 'SecurePass123!', 'name': 'John Doe' } ) user = response.json() print(user) ``` ``` ### Example 2: GraphQL API Documentation ```markdown ## User Query Fetch user information by ID. **Query:** ```graphql query GetUser($id: ID!) { user(id: $id) { id email name role createdAt posts { id title publishedAt } } } ``` **Variables:** ```json { "id": "usr_1234567890" } ``` **Response:** ```json { "data": { "user": { "id": "usr_1234567890", "email": "[email protected]", "name": "John Doe", "role": "user", "createdAt": "2026-01-20T10:30:00Z", "posts": [ { "id": "post_123", "title": "My First Post", "publishedAt": "2026-01-21T14:00:00Z" } ] } } } ``` **Errors:** ```json { "errors": [ { "message": "User not found", "extensions": { "code": "USER_NOT_FOUND", "userId": "usr_1234567890" } } ] } ``` ``` ### Example 3: Authentication Documentation ```markdown ## Authentication All API requests require authentication using Bearer tokens. ### Getting a Token **Endpoint:** `POST /api/v1/auth/login` **Request:** ```json { "email": "[email protected]", "password": "your-password" } ``` **Response:** ```json { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expiresIn": 3600, "refreshToken": "refresh_token_here" } ``` ### Using the Token Include the token in the Authorization header: ``` Authorization: Bearer YOUR_TOKEN ``` ### Token Expiration Tokens expire after 1 hour. Use the refresh token to get a new access token: **Endpoint:** `POST /api/v1/auth/refresh` **Request:** ```json { "refreshToken": "refresh_token_here" } ``` ``` ## Best Practices ### ✅ Do This - **Be Consistent** - Use the same format for all endpoints - **Include Examples** - Provide working code examples in multiple languages - **Document Errors** - List all possible error codes and their meanings - **Show Real Data** - Use realistic example data, not "foo" and "bar" - **Explain Parameters** - Describe what each parameter does and its constraints - **Version Your API** - Include version numbers in URLs (/api/v1/) - **Add Timestamps** - Show when documentation was last updated - **Link Related Endpoints** - Help users discover related functionality - **Include Rate Limits** - Document any rate limiting policies - **Provide Postman Collection** - Make it easy to test your API ### ❌ Don't Do This - **Don't Skip Error Cases** - Users need to know what can go wrong - **Don't Use Vague Descriptions** - "Gets data" is not helpful - **Don't Forget Authentication** - Always document auth requirements - **Don't Ignore Edge Cases** - Document pagination, filtering, sorting - **Don't Leave Examples Broken** - Test all code examples - **Don't Use Outdated Info** - Keep documentation in sync with code - **Don't Overcomplicate** - Keep it simple and scannable - **Don't Forget Response Headers** - Document important headers ## Documentation Structure ### Recommended Sections 1. **Introduction** - What the API does - Base URL - API version - Support contact 2. **Authentication** - How to authenticate - Token management - Security best practices 3. **Quick Start** - Simple example to get started - Common use case walkthrough 4. **Endpoints** - Organized by resource - Full details for each endpoint 5. **Data Models** - Schema definitions - Field descriptions - Validation rules 6. **Error Handling** - Error code reference - Error response format - Troubleshooting guide 7. **Rate Limiting** - Limits and quotas - Headers to check - Handling rate limit errors 8. **Changelog** - API version history - Breaking changes - Deprecation notices 9. **SDKs and Tools** - Official client libraries - Postman collection - OpenAPI specification ## Common Pitfalls ### Problem: Documentation Gets Out of Sync **Symptoms:** Examples don't work, parameters are wrong, endpoints return different data **Solution:** - Generate docs from code comments/annotations - Use tools like Swagger/OpenAPI - Add API tests that validate documentation - Review docs with every API change ### Problem: Missing Error Documentation **Symptoms:** Users don't know how to handle errors, support tickets increase **Solution:** - Document every possible error code - Provide clear error messages - Include troubleshooting steps - Show example error responses ### Problem: Examples Don't Work **Symptoms:** Users can't get started, frustration increases **Solution:** - Test every code example - Use real, working endpoints - Include complete examples (not fragments) - Provide a sandbox environment ### Problem: Unclear Parameter Requirements **Symptoms:** Users send invalid requests, validation errors **Solution:** - Mark required vs optional clearly - Document data types and formats - Show validation rules - Provide example values ## Tools and Formats ### OpenAPI/Swagger Generate interactive documentation: ```yaml openapi: 3.0.0 info: title: My API version: 1.0.0 paths: /users: post: summary: Create a new user requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserRequest' ``` ### Postman Collection Export collection for easy testing: ```json { "info": { "name": "My API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ { "name": "Create User", "request": { "method": "POST", "url": "{{baseUrl}}/api/v1/users" } } ] } ``` ## Related Skills - `@doc-coauthoring` - For collaborative documentation writing - `@copywriting` - For clear, user-friendly descriptions - `@test-driven-development` - For ensuring API behavior matches docs - `@systematic-debugging` - For troubleshooting API issues ## Additional Resources - [OpenAPI Specification](https://swagger.io/specification/) - [REST API Best Practices](https://restfulapi.net/) - [GraphQL Documentation](https://graphql.org/learn/) - [API Design Patterns](https://www.apiguide.com/) - [Postman Documentation](https://learning.postman.com/docs/) --- **Pro Tip:** Keep your API documentation as close to your code as possible. Use tools that generate docs from code comments to ensure they stay in sync!