alirezarezvani

documentation

@alirezarezvani/documentation
alirezarezvani
435
108 forks
Updated 1/18/2026
View on GitHub

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.

Installation

$skills install @alirezarezvani/documentation
Claude Code
Cursor
Copilot
Codex
Antigravity

Details

Repositoryalirezarezvani/claude-code-tresor
Pathskills/documentation/api-documenter/SKILL.md
Branchmain
Scoped Name@alirezarezvani/documentation

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

skills list

Skill Instructions

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

More by alirezarezvani

View all
marketing-strategy-pmm
774

Product marketing, positioning, GTM strategy, and competitive intelligence. Includes ICP definition, April Dunford positioning methodology, launch playbooks, competitive battlecards, and international market entry guides. Use when developing positioning, planning product launches, creating messaging, analyzing competitors, entering new markets, enabling sales, or when user mentions product marketing, positioning, GTM, go-to-market, competitive analysis, market entry, or sales enablement.

agile-product-owner
774

Agile product ownership toolkit for Senior Product Owner including INVEST-compliant user story generation, sprint planning, backlog management, and velocity tracking. Use for story writing, sprint planning, stakeholder communication, and agile ceremonies.

senior-prompt-engineer
774

World-class prompt engineering skill for LLM optimization, prompt patterns, structured outputs, and AI product development. Expertise in Claude, GPT-4, prompt design patterns, few-shot learning, chain-of-thought, and AI evaluation. Includes RAG optimization, agent design, and LLM system architecture. Use when building AI products, optimizing LLM performance, designing agentic systems, or implementing advanced prompting techniques.

mdr-745-specialist
774

EU MDR 2017/745 regulation specialist and consultant for medical device requirement management. Provides comprehensive MDR compliance expertise, gap analysis, technical documentation guidance, clinical evidence requirements, and post-market surveillance implementation. Use for MDR compliance assessment, classification decisions, technical file preparation, and regulatory requirement interpretation.