API Documentation Generator Command

Generate API documentation from code

Instructions

Follow this systematic approach to create API documentation: $ARGUMENTS

Code Analysis and Discovery
- Scan the codebase for API endpoints, routes, and handlers
- Identify REST APIs, GraphQL schemas, and RPC services
- Map out controller classes, route definitions, and middleware
- Discover request/response models and data structures
Documentation Tool Selection
- Choose appropriate documentation tools based on stack:
  - OpenAPI/Swagger: REST APIs with interactive documentation
  - GraphQL: GraphiQL, GraphQL Playground, or Apollo Studio
  - Postman: API collections and documentation
  - Insomnia: API design and documentation
  - Redoc: Alternative OpenAPI renderer
  - API Blueprint: Markdown-based API documentation

API Specification Generation

For REST APIs with OpenAPI:

openapi: 3.0.0
info:
  title: $ARGUMENTS API
  version: 1.0.0
  description: Comprehensive API for $ARGUMENTS
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

Endpoint Documentation
- Document all HTTP methods (GET, POST, PUT, DELETE, PATCH)
- Specify request parameters (path, query, header, body)
- Define response schemas and status codes
- Include error responses and error codes
- Document authentication and authorization requirements
Request/Response Examples
- Provide realistic request examples for each endpoint
- Include sample response data with proper formatting
- Show different response scenarios (success, error, edge cases)
- Document content types and encoding
Authentication Documentation
- Document authentication methods (API keys, JWT, OAuth)
- Explain authorization scopes and permissions
- Provide authentication examples and token formats
- Document session management and refresh token flows
Data Model Documentation
- Define all data schemas and models
- Document field types, constraints, and validation rules
- Include relationships between entities
- Provide example data structures
Error Handling Documentation
- Document all possible error responses
- Explain error codes and their meanings
- Provide troubleshooting guidance
- Include rate limiting and throttling information

Interactive Documentation Setup

Swagger UI Integration:

<!DOCTYPE html>
<html>
<head>
  <title>API Documentation</title>
  <link rel="stylesheet" type="text/css" href="./swagger-ui-bundle.css" />
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="./swagger-ui-bundle.js"></script>
  <script>
    SwaggerUIBundle({
      url: './api-spec.yaml',
      dom_id: '#swagger-ui'
    });
  </script>
</body>
</html>

Code Annotation and Comments
- Add inline documentation to API handlers
- Use framework-specific annotation tools:
  - Java: @ApiOperation, @ApiParam (Swagger annotations)
  - Python: Docstrings with FastAPI or Flask-RESTX
  - Node.js: JSDoc comments with swagger-jsdoc
  - C#: XML documentation comments

Automated Documentation Generation

For Node.js/Express:

const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'API Documentation',
      version: '1.0.0',
    },
  },
  apis: ['./routes/*.js'],
};

const specs = swaggerJsdoc(options);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));

Testing Integration
- Generate API test collections from documentation
- Include test scripts and validation rules
- Set up automated API testing
- Document test scenarios and expected outcomes
Version Management
- Document API versioning strategy
- Maintain documentation for multiple API versions
- Document deprecation timelines and migration guides
- Track breaking changes between versions
Performance Documentation
- Document rate limits and throttling policies
- Include performance benchmarks and SLAs
- Document caching strategies and headers
- Explain pagination and filtering options
SDK and Client Library Documentation
- Generate client libraries from API specifications
- Document SDK usage and examples
- Provide quickstart guides for different languages
- Include integration examples and best practices
Environment-Specific Documentation
- Document different environments (dev, staging, prod)
- Include environment-specific endpoints and configurations
- Document deployment and configuration requirements
- Provide environment setup instructions
Security Documentation
- Document security best practices
- Include CORS and CSP policies
- Document input validation and sanitization
- Explain security headers and their purposes
Maintenance and Updates
- Set up automated documentation updates
- Create processes for keeping documentation current
- Review and validate documentation regularly
- Integrate documentation reviews into development workflow

Framework-Specific Examples:

FastAPI (Python):

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(title="My API", version="1.0.0")

class User(BaseModel):
    id: int
    name: str
    email: str

@app.get("/users/{user_id}", response_model=User)
async def get_user(user_id: int):
    """Get a user by ID."""
    return {"id": user_id, "name": "John", "email": "john@example.com"}

Spring Boot (Java):

@RestController
@Api(tags = "Users")
public class UserController {
    
    @GetMapping("/users/{id}")
    @ApiOperation(value = "Get user by ID")
    public ResponseEntity<User> getUser(
        @PathVariable @ApiParam("User ID") Long id) {
        // Implementation
    }
}

Remember to keep documentation up-to-date with code changes and make it easily accessible to both internal teams and external consumers.

/doc-api

API Documentation Generator Command

Instructions

Other plugins with /doc-api