/api-documenter

name: api-documenter
description: Auto-generate API documentation from code and comments. Use when API endpoints change, or user mentions API docs. Creates OpenAPI/Swagger specs from code. Triggers on API file changes, documentation requests, endpoint additions.
allowed-tools: Read, Write, Grep

API Documenter Skill

Auto-generate API documentation from code.

When I Activate

• ✅ API endpoints added/modified
• ✅ User mentions API docs, OpenAPI, or Swagger
• ✅ Route files changed
• ✅ Controller files modified
• ✅ Documentation needed

What I Generate

OpenAPI 3.0 Specifications

• Endpoint descriptions
• Request/response schemas
• Authentication requirements
• Example payloads
• Error responses

Formats Supported

• OpenAPI 3.0 (JSON/YAML)
• Swagger 2.0
• API Blueprint
• RAML

Examples

Express.js Endpoint

// You write:
/**
 * Get user by ID
 * @param {string} id - User ID
 * @returns {User} User object
 */
app.get('/api/users/:id', async (req, res) => {
  const user = await User.findById(req.params.id);
  res.json(user);
});

// I auto-generate OpenAPI spec:
paths:
  /api/users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          description: User ID
          schema:
            type: string
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: "123"
                name: "John Doe"
                email: "john@example.com"
        '404':
          description: User not found

FastAPI Endpoint

# You write:
@app.get("/users/{user_id}")
def get_user(user_id: int) -> User:
    """Get user by ID"""
    return db.query(User).filter(User.id == user_id).first()

// I auto-generate:
paths:
  /users/{user_id}:
    get:
      summary: Get user by ID
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Complete OpenAPI Document

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: API for user management

servers:
  - url: https://api.example.com/v1

paths:
  /api/users:
    get:
      summary: List all users
      responses:
        '200':
          description: Users array
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email

Detection Logic

Framework Detection

I recognize these frameworks automatically:

• **Express.js** (Node.js)
• **FastAPI** (Python)
• **Django REST** (Python)
• **Spring Boot** (Java)
• **Gin** (Go)
• **Rails** (Ruby)

Comment Parsing

I extract documentation from:

• JSDoc comments (`/** */`)
• Python docstrings
• JavaDoc
• Inline comments with decorators

Documentation Enhancement

Missing Information

// Your code:
app.post('/api/users', (req, res) => {
  User.create(req.body);
});

// I suggest additions:
/**
 * Create new user
 * @param {Object} req.body - User data
 * @param {string} req.body.name - User name (required)
 * @param {string} req.body.email - User email (required)
 * @returns {User} Created user
 * @throws {400} Invalid input
 * @throws {409} Email already exists
 */

Example Generation

I generate realistic examples:

{
  "id": "usr_1234567890",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "createdAt": "2025-10-24T10:30:00Z",
  "verified": true
}

Relationship with @docs-writer

**Me (Skill):** Auto-generate API specs from code **@docs-writer (Sub-Agent):** Comprehensive user guides and tutorials

Workflow

1. I generate OpenAPI spec 2. You need user guide → Invoke **@docs-writer** sub-agent 3. Sub-agent creates complete documentation site

Integration

With Swagger UI

// app.js
const swaggerUi = require('swagger-ui-express');
const spec = require('./openapi.json'); // Generated by skill

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(spec));

With Postman

Export generated OpenAPI spec:

# Import into Postman for API testing
File → Import → openapi.json

With Documentation Sites

• **Docusaurus**: API docs plugin
• **MkDocs**: OpenAPI plugin
• **Redoc**: OpenAPI renderer
• **Stoplight**: API design platform

Customization

Add company-specific documentation standards:

cp -r ~/.claude/skills/documentation/api-documenter \
      ~/.claude/skills/documentation/company-api-documenter

# Edit to add:
# - Company API standards
# - Custom response formats
# - Internal schemas

Sandboxing Compatibility

**Works without sandboxing:** ✅ Yes **Works with sandboxing:** ✅ Yes

• **Filesystem**: Writes OpenAPI files
• **Network**: None required
• **Configuration**: None required

Best Practices

1. **Keep comments updated** - Documentation follows code 2. **Use type hints** - TypeScript, Python types help 3. **Include examples** - Real-world request/response 4. **Document errors** - All possible error responses 5. **Version your API** - Include version in endpoints

Related Tools

• **@docs-writer sub-agent**: User guides and tutorials
• **readme-updater skill**: Keep README current
• **/docs-gen command**: Full documentation generation