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