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.