Agent skill

api-documenter

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.

View SKILL.md on GitHub Repository
Stars 675
Forks 152

Install this agent skill to your Project

npx add-skill https://github.com/alirezarezvani/claude-code-tresor/tree/main/skills/documentation/api-documenter

SKILL.md

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

javascript
// 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

python
# 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

yaml
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

javascript
// 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:

json
{
  "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

javascript
// 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:

bash
# 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:

bash
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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

alirezarezvani/claude-code-tresor

readme-updater

Keep README files current with project changes. Use when project structure changes, features added, or setup instructions modified. Suggests README updates based on code changes. Triggers on significant project changes, new features, dependency changes.

675 152
Explore
alirezarezvani/claude-code-tresor

security-auditor

Continuous security vulnerability scanning for OWASP Top 10, common vulnerabilities, and insecure patterns. Use when reviewing code, before deployments, or on file changes. Scans for SQL injection, XSS, secrets exposure, auth issues. Triggers on file changes, security mentions, deployment prep.

675 152
Explore
alirezarezvani/claude-code-tresor

secret-scanner

Detect exposed secrets, API keys, credentials, and tokens in code. Use before commits, on file saves, or when security is mentioned. Prevents accidental secret exposure. Triggers on file changes, git commits, security checks, .env file modifications.

675 152
Explore
alirezarezvani/claude-code-tresor

dependency-auditor

Check dependencies for known vulnerabilities using npm audit, pip-audit, etc. Use when package.json or requirements.txt changes, or before deployments. Alerts on vulnerable dependencies. Triggers on dependency file changes, deployment prep, security mentions.

675 152
Explore
alirezarezvani/claude-code-tresor

code-reviewer

Automatic code quality and best practices analysis. Use proactively when files are modified, saved, or committed. Analyzes code style, patterns, potential bugs, and security basics. Triggers on file changes, git diff, code edits, quality mentions.

675 152
Explore
alirezarezvani/claude-code-tresor

test-generator

Automatically suggest tests for new functions and components. Use when new code is written, functions added, or user mentions testing. Creates test scaffolding with Jest, Vitest, Pytest patterns. Triggers on new functions, components, test requests, testing mentions.

675 152
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results