wehub-resource-sync
1 line
7.8 KiB
JSON
1 line
7.8 KiB
JSON
{"content": "---\nallowed-tools: Read, Write, Edit, Bash\nargument-hint: [api-type] | --openapi | --graphql | --rest | --grpc | --interactive\ndescription: Generate comprehensive API documentation from code with interactive examples and testing capabilities\n---\n\n# API Documentation Generator\n\nGenerate API documentation from code: $ARGUMENTS\n\n## Current API Context\n\n- API endpoints: !`find . -name \"*route*\" -o -name \"*controller*\" -o -name \"*api*\" | head -5`\n- API specs: !`find . -name \"*openapi*\" -o -name \"*swagger*\" -o -name \"*.graphql\" | head -3`\n- Server framework: @package.json or detect from imports\n- Existing docs: @docs/api/ or @api-docs/ (if exists)\n- Test files: !`find . -name \"*test*\" -path \"*/api/*\" | head -3`\n\n## Task\n\nGenerate comprehensive API documentation with interactive features: $ARGUMENTS\n\n1. **Code Analysis and Discovery**\n - Scan the codebase for API endpoints, routes, and handlers\n - Identify REST APIs, GraphQL schemas, and RPC services\n - Map out controller classes, route definitions, and middleware\n - Discover request/response models and data structures\n\n2. **Documentation Tool Selection**\n - Choose appropriate documentation tools based on stack:\n - **OpenAPI/Swagger**: REST APIs with interactive documentation\n - **GraphQL**: GraphiQL, GraphQL Playground, or Apollo Studio\n - **Postman**: API collections and documentation\n - **Insomnia**: API design and documentation\n - **Redoc**: Alternative OpenAPI renderer\n - **API Blueprint**: Markdown-based API documentation\n\n3. **API Specification Generation**\n \n **For REST APIs with OpenAPI:**\n ```yaml\n openapi: 3.0.0\n info:\n title: $ARGUMENTS API\n version: 1.0.0\n description: Comprehensive API for $ARGUMENTS\n servers:\n - url: https://api.example.com/v1\n paths:\n /users:\n get:\n summary: List users\n parameters:\n - name: page\n in: query\n schema:\n type: integer\n responses:\n '200':\n description: Successful response\n content:\n application/json:\n schema:\n type: array\n items:\n $ref: '#/components/schemas/User'\n components:\n schemas:\n User:\n type: object\n properties:\n id:\n type: integer\n name:\n type: string\n email:\n type: string\n ```\n\n4. **Endpoint Documentation**\n - Document all HTTP methods (GET, POST, PUT, DELETE, PATCH)\n - Specify request parameters (path, query, header, body)\n - Define response schemas and status codes\n - Include error responses and error codes\n - Document authentication and authorization requirements\n\n5. **Request/Response Examples**\n - Provide realistic request examples for each endpoint\n - Include sample response data with proper formatting\n - Show different response scenarios (success, error, edge cases)\n - Document content types and encoding\n\n6. **Authentication Documentation**\n - Document authentication methods (API keys, JWT, OAuth)\n - Explain authorization scopes and permissions\n - Provide authentication examples and token formats\n - Document session management and refresh token flows\n\n7. **Data Model Documentation**\n - Define all data schemas and models\n - Document field types, constraints, and validation rules\n - Include relationships between entities\n - Provide example data structures\n\n8. **Error Handling Documentation**\n - Document all possible error responses\n - Explain error codes and their meanings\n - Provide troubleshooting guidance\n - Include rate limiting and throttling information\n\n9. **Interactive Documentation Setup**\n \n **Swagger UI Integration:**\n ```html\n <!DOCTYPE html>\n <html>\n <head>\n <title>API Documentation</title>\n <link rel=\"stylesheet\" type=\"text/css\" href=\"./swagger-ui-bundle.css\" />\n </head>\n <body>\n <div id=\"swagger-ui\"></div>\n <script src=\"./swagger-ui-bundle.js\"></script>\n <script>\n SwaggerUIBundle({\n url: './api-spec.yaml',\n dom_id: '#swagger-ui'\n });\n </script>\n </body>\n </html>\n ```\n\n10. **Code Annotation and Comments**\n - Add inline documentation to API handlers\n - Use framework-specific annotation tools:\n - **Java**: @ApiOperation, @ApiParam (Swagger annotations)\n - **Python**: Docstrings with FastAPI or Flask-RESTX\n - **Node.js**: JSDoc comments with swagger-jsdoc\n - **C#**: XML documentation comments\n\n11. **Automated Documentation Generation**\n \n **For Node.js/Express:**\n ```javascript\n const swaggerJsdoc = require('swagger-jsdoc');\n const swaggerUi = require('swagger-ui-express');\n \n const options = {\n definition: {\n openapi: '3.0.0',\n info: {\n title: 'API Documentation',\n version: '1.0.0',\n },\n },\n apis: ['./routes/*.js'],\n };\n \n const specs = swaggerJsdoc(options);\n app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));\n ```\n\n12. **Testing Integration**\n - Generate API test collections from documentation\n - Include test scripts and validation rules\n - Set up automated API testing\n - Document test scenarios and expected outcomes\n\n13. **Version Management**\n - Document API versioning strategy\n - Maintain documentation for multiple API versions\n - Document deprecation timelines and migration guides\n - Track breaking changes between versions\n\n14. **Performance Documentation**\n - Document rate limits and throttling policies\n - Include performance benchmarks and SLAs\n - Document caching strategies and headers\n - Explain pagination and filtering options\n\n15. **SDK and Client Library Documentation**\n - Generate client libraries from API specifications\n - Document SDK usage and examples\n - Provide quickstart guides for different languages\n - Include integration examples and best practices\n\n16. **Environment-Specific Documentation**\n - Document different environments (dev, staging, prod)\n - Include environment-specific endpoints and configurations\n - Document deployment and configuration requirements\n - Provide environment setup instructions\n\n17. **Security Documentation**\n - Document security best practices\n - Include CORS and CSP policies\n - Document input validation and sanitization\n - Explain security headers and their purposes\n\n18. **Maintenance and Updates**\n - Set up automated documentation updates\n - Create processes for keeping documentation current\n - Review and validate documentation regularly\n - Integrate documentation reviews into development workflow\n\n**Framework-Specific Examples:**\n\n**FastAPI (Python):**\n```python\nfrom fastapi import FastAPI\nfrom pydantic import BaseModel\n\napp = FastAPI(title=\"My API\", version=\"1.0.0\")\n\nclass User(BaseModel):\n id: int\n name: str\n email: str\n\n@app.get(\"/users/{user_id}\", response_model=User)\nasync def get_user(user_id: int):\n \"\"\"Get a user by ID.\"\"\"\n return {\"id\": user_id, \"name\": \"John\", \"email\": \"john@example.com\"}\n```\n\n**Spring Boot (Java):**\n```java\n@RestController\n@Api(tags = \"Users\")\npublic class UserController {\n \n @GetMapping(\"/users/{id}\")\n @ApiOperation(value = \"Get user by ID\")\n public ResponseEntity<User> getUser(\n @PathVariable @ApiParam(\"User ID\") Long id) {\n // Implementation\n }\n}\n```\n\nRemember to keep documentation up-to-date with code changes and make it easily accessible to both internal teams and external consumers."} |