Claude GitHub Copilot Skill

api-documentation

Use when source code has changed and API docs are stale, or a new endpoint lacks documentation — generates accurate docs from implementation, not guesswork.

LLM Mart · 0 points · 3 views 0 listing impressions 0 install-command copies
Download drvoss-everything-copilot-cli-skills_documentation_api-documentation-1ca2355.zip · 2 KB

Install

skills CLI npx skills add https://github.com/drvoss/everything-copilot-cli/tree/main/skills/documentation/api-documentation
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install drvoss-everything-copilot-cli@llmmart
Git git clone https://github.com/drvoss/everything-copilot-cli.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole drvoss/everything-copilot-cli collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

API Documentation

When to Use

  • Building or updating REST/GraphQL API documentation
  • Onboarding new developers who need to understand available endpoints
  • Preparing API reference docs for external consumers
  • Ensuring API docs stay synchronized with implementation
  • Creating OpenAPI/Swagger specifications from existing code

Prerequisites

  • API source code with route definitions
  • Understanding of the API framework (Express, FastAPI, Gin, etc.)
  • Knowledge of request/response formats and authentication requirements

Workflow

1. Discover All Endpoints

# Express / Node.js
grep -rn "router\.\(get\|post\|put\|delete\|patch\)\|app\.\(get\|post\|put\|delete\|patch\)" src/ --include="*.ts" --include="*.js"

# FastAPI / Python
grep -rn "@app\.\(get\|post\|put\|delete\)\|@router\." src/ --include="*.py"

# Go / Gin
grep -rn "\.GET\|\.POST\|\.PUT\|\.DELETE" . --include="*.go"

Use explore agent for a comprehensive map:

task agent_type: "explore"
prompt: "Map all API endpoints in this project. For each endpoint list: HTTP method, path, handler function name, file location, and any middleware applied."

2. Document Each Endpoint

For each endpoint, capture:

## POST /api/users

Create a new user account.

**Authentication:** Bearer token required

**Request Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | Valid email address |
| name | string | Yes | Display name (1-100 chars) |
| role | string | No | User role (default: "viewer") |

**Response 201:**
```json
{
  "id": "usr_abc123",
  "email": "user@example.com",
  "name": "Jane Doe",
  "role": "viewer",
  "createdAt": "2024-01-15T10:30:00Z"
}

Error Responses:

Status Description
400 Invalid request body
409 Email already exists
401 Missing or invalid auth token

### 3. Extract Types and Schemas
```powershell
# Find request/response type definitions
grep -rn "interface.*Request\|interface.*Response\|type.*Payload" src/ --include="*.ts" -A 10

# Find validation schemas (Zod, Joi, etc.)
grep -rn "z\.object\|Joi\.object\|Schema" src/ --include="*.ts" -A 10

4. Document Authentication

# Find auth middleware and configuration
grep -rn "auth\|jwt\|bearer\|apiKey\|passport" src/middleware/ --include="*.ts" -A 5
## Authentication

All endpoints except `POST /auth/login` require a Bearer token.

```bash
curl -H "Authorization: Bearer <token>" https://api.example.com/users

Obtaining a Token

curl -X POST https://api.example.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secret"}'

### 5. Add Working Examples
```powershell
# Test each documented example against a running server
# Start the dev server
npm run dev  # mode: async, detach: true

# Verify an endpoint
curl -s http://localhost:3000/api/health | python -m json.tool

6. Generate OpenAPI Spec (Optional)

# If using a framework that supports auto-generation
npx swagger-jsdoc -d src/swagger-config.js -o docs/openapi.json

# Or generate from TypeScript types
npx ts-to-openapi --input src/types/ --output docs/openapi.yaml

Examples

Documenting a CRUD API

# 1. Find all route files
# (Copilot glob tool) pattern="src/routes/**/*.ts"

# 2. For each route file, extract endpoints and their handlers
grep -rn "router\." src/routes/users.ts -A 3

# 3. Find the handler implementation for request/response details
grep -rn "export.*function\|export.*const.*=" src/controllers/users.ts -A 15

Quick API Reference Table

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | /api/users | List all users | Yes |
| POST | /api/users | Create user | Yes |
| GET | /api/users/:id | Get user by ID | Yes |
| PUT | /api/users/:id | Update user | Yes |
| DELETE | /api/users/:id | Delete user | Admin |

Tips

  • Generate from code when possible — manually written docs drift from reality
  • Include curl examples for every endpoint — they're the most portable format
  • Document error responses, not just success cases
  • Add rate limiting and pagination details if applicable
  • Version your API docs alongside API code (same branch, same PR)
  • Use task agent to verify documented curl commands actually work against the API
  • Include a Postman collection or similar importable format for API consumers
Files (everything-copilot-cli)
  • SKILL.md 4.7 KB
    ---
    name: api-documentation
    license: MIT
    description: Use when source code has changed and API docs are stale, or a new endpoint lacks documentation — generates accurate docs from implementation, not guesswork.
    metadata:
      category: documentation
      agent_type: general-purpose
    ---
    
    # API Documentation
    
    ## When to Use
    
    - Building or updating REST/GraphQL API documentation
    - Onboarding new developers who need to understand available endpoints
    - Preparing API reference docs for external consumers
    - Ensuring API docs stay synchronized with implementation
    - Creating OpenAPI/Swagger specifications from existing code
    
    ## Prerequisites
    
    - API source code with route definitions
    - Understanding of the API framework (Express, FastAPI, Gin, etc.)
    - Knowledge of request/response formats and authentication requirements
    
    ## Workflow
    
    ### 1. Discover All Endpoints
    
    ```powershell
    # Express / Node.js
    grep -rn "router\.\(get\|post\|put\|delete\|patch\)\|app\.\(get\|post\|put\|delete\|patch\)" src/ --include="*.ts" --include="*.js"
    
    # FastAPI / Python
    grep -rn "@app\.\(get\|post\|put\|delete\)\|@router\." src/ --include="*.py"
    
    # Go / Gin
    grep -rn "\.GET\|\.POST\|\.PUT\|\.DELETE" . --include="*.go"
    ```
    
    Use `explore` agent for a comprehensive map:
    
    ```text
    task agent_type: "explore"
    prompt: "Map all API endpoints in this project. For each endpoint list: HTTP method, path, handler function name, file location, and any middleware applied."
    ```
    
    ### 2. Document Each Endpoint
    
    For each endpoint, capture:
    
    ```markdown
    ## POST /api/users
    
    Create a new user account.
    
    **Authentication:** Bearer token required
    
    **Request Body:**
    | Field | Type | Required | Description |
    |-------|------|----------|-------------|
    | email | string | Yes | Valid email address |
    | name | string | Yes | Display name (1-100 chars) |
    | role | string | No | User role (default: "viewer") |
    
    **Response 201:**
    ```json
    {
      "id": "usr_abc123",
      "email": "user@example.com",
      "name": "Jane Doe",
      "role": "viewer",
      "createdAt": "2024-01-15T10:30:00Z"
    }
    ```
    
    **Error Responses:**
    
    | Status | Description |
    |--------|-------------|
    | 400 | Invalid request body |
    | 409 | Email already exists |
    | 401 | Missing or invalid auth token |
    
    ```text
    
    ### 3. Extract Types and Schemas
    ```powershell
    # Find request/response type definitions
    grep -rn "interface.*Request\|interface.*Response\|type.*Payload" src/ --include="*.ts" -A 10
    
    # Find validation schemas (Zod, Joi, etc.)
    grep -rn "z\.object\|Joi\.object\|Schema" src/ --include="*.ts" -A 10
    ```
    
    ### 4. Document Authentication
    
    ```powershell
    # Find auth middleware and configuration
    grep -rn "auth\|jwt\|bearer\|apiKey\|passport" src/middleware/ --include="*.ts" -A 5
    ```
    
    ```markdown
    ## Authentication
    
    All endpoints except `POST /auth/login` require a Bearer token.
    
    ```bash
    curl -H "Authorization: Bearer <token>" https://api.example.com/users
    ```
    
    ### Obtaining a Token
    
    ```bash
    curl -X POST https://api.example.com/auth/login \
      -H "Content-Type: application/json" \
      -d '{"email": "user@example.com", "password": "secret"}'
    ```
    
    ```text
    
    ### 5. Add Working Examples
    ```powershell
    # Test each documented example against a running server
    # Start the dev server
    npm run dev  # mode: async, detach: true
    
    # Verify an endpoint
    curl -s http://localhost:3000/api/health | python -m json.tool
    ```
    
    ### 6. Generate OpenAPI Spec (Optional)
    
    ```powershell
    # If using a framework that supports auto-generation
    npx swagger-jsdoc -d src/swagger-config.js -o docs/openapi.json
    
    # Or generate from TypeScript types
    npx ts-to-openapi --input src/types/ --output docs/openapi.yaml
    ```
    
    ## Examples
    
    ### Documenting a CRUD API
    
    ```powershell
    # 1. Find all route files
    # (Copilot glob tool) pattern="src/routes/**/*.ts"
    
    # 2. For each route file, extract endpoints and their handlers
    grep -rn "router\." src/routes/users.ts -A 3
    
    # 3. Find the handler implementation for request/response details
    grep -rn "export.*function\|export.*const.*=" src/controllers/users.ts -A 15
    ```
    
    ### Quick API Reference Table
    
    ```markdown
    | Method | Path | Description | Auth |
    |--------|------|-------------|------|
    | GET | /api/users | List all users | Yes |
    | POST | /api/users | Create user | Yes |
    | GET | /api/users/:id | Get user by ID | Yes |
    | PUT | /api/users/:id | Update user | Yes |
    | DELETE | /api/users/:id | Delete user | Admin |
    ```
    
    ## Tips
    
    - **Generate from code** when possible — manually written docs drift from reality
    - Include `curl` examples for every endpoint — they're the most portable format
    - Document error responses, not just success cases
    - Add rate limiting and pagination details if applicable
    - Version your API docs alongside API code (same branch, same PR)
    - Use `task` agent to verify documented curl commands actually work against the API
    - Include a Postman collection or similar importable format for API consumers
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.