/doc-api

Generate API documentation from code

qdhenry@qdhenry

GitHub

From plugin

claude-command-suite

1.3k199 skills89 agents199 commands

Install

$ npx -y skills add qdhenry/Claude-Command-Suite --agent claude-code

How it fires

How this command gets triggered: by you, by Claude, or both.

Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/doc-api

Context preview

What this command does when you run it.

Generate API documentation from code

Command definition

doc-api.md

API Documentation Generator Command

Generate API documentation from code

Instructions

Follow this systematic approach to create API documentation: **$ARGUMENTS**

1. **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

2. **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

3. **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

4. **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

5. **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

6. **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

7. **Data Model Documentation**

Define all data schemas and models
Document field types, constraints, and validation rules
Include relationships between entities
Provide example data structures

8. **Error Handling Documentation**

Document all possible error responses
Explain error codes and their meanings
Provide troubleshooting guidance
Include rate limiting and throttling information

9. **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>

10. **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

11. **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));

12. **Testing Integration**