Agent skill

api-documentation

View SKILL.md on GitHub Repository
Stars 0
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/brendendurham/claude-code-config/tree/main/skills/api-documentation

SKILL.md

API Documentation Skill

Generate comprehensive API documentation including OpenAPI/Swagger specs from source code.

When to Use

  • User asks to "document API" or "generate OpenAPI spec"
  • User wants Swagger documentation
  • User needs GraphQL schema documentation
  • User asks to document endpoints

Supported API Types

REST APIs

  • Express.js, Fastify, Koa (Node.js)
  • Flask, FastAPI, Django (Python)
  • Spring Boot (Java)
  • Gin, Echo, Fiber (Go)
  • Rails, Sinatra (Ruby)

GraphQL APIs

  • Apollo Server
  • GraphQL Yoga
  • Strawberry, Ariadne (Python)
  • gqlgen (Go)

Documentation Process

Step 1: Discover Endpoints

Scan the codebase for API definitions:

bash
# Find route definitions (Node.js/Express)
grep -r "app\.\(get\|post\|put\|patch\|delete\)" --include="*.js" --include="*.ts"

# Find FastAPI routes (Python)
grep -r "@app\.\(get\|post\|put\|patch\|delete\)" --include="*.py"

# Find Spring mappings (Java)
grep -r "@\(Get\|Post\|Put\|Delete\)Mapping" --include="*.java"

# Find GraphQL resolvers
grep -r "Query\|Mutation\|Subscription" --include="*.graphql"

Step 2: Extract Route Information

For each endpoint, gather:

  • HTTP method (GET, POST, PUT, PATCH, DELETE)
  • Path with parameters (/users/:id or /users/{id})
  • Request body schema
  • Query parameters
  • Path parameters
  • Headers (especially auth)
  • Response schemas (success and error)

Step 3: Generate Schema Definitions

Analyze types, interfaces, and models:

  • TypeScript interfaces
  • Python dataclasses/Pydantic models
  • Java DTOs
  • Database models
  • Validation schemas (Zod, Joi, etc.)

OpenAPI 3.0 Output Format

yaml
openapi: 3.0.3
info:
  title: API Name
  description: |
    Brief description of the API.

    ## Authentication
    Describe auth method here.
  version: 1.0.0
  contact:
    name: API Support
    email: support@example.com

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

tags:
  - name: users
    description: User management operations
  - name: auth
    description: Authentication endpoints

paths:
  /users:
    get:
      tags:
        - users
      summary: List all users
      description: Retrieve a paginated list of users
      operationId: listUsers
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Items per page
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - users
      summary: Create a new user
      operationId: createUser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: User already exists

  /users/{id}:
    get:
      tags:
        - users
      summary: Get user by ID
      operationId: getUserById
      parameters:
        - name: id
          in: path
          required: true
          description: User ID
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          example: "123e4567-e89b-12d3-a456-426614174000"
        email:
          type: string
          format: email
          example: "user@example.com"
        name:
          type: string
          example: "John Doe"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    CreateUserRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password
          minLength: 8
        name:
          type: string

    UserList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/Pagination'

    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        totalPages:
          type: integer

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - bearerAuth: []

GraphQL Schema Documentation

For GraphQL APIs, generate SDL with descriptions:

graphql
"""
User account information
"""
type User {
  """Unique identifier"""
  id: ID!

  """User's email address"""
  email: String!

  """Display name"""
  name: String

  """Account creation timestamp"""
  createdAt: DateTime!

  """User's posts"""
  posts(first: Int = 10, after: String): PostConnection!
}

"""
Paginated post results
"""
type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}

type Query {
  """Get current authenticated user"""
  me: User

  """Get user by ID"""
  user(id: ID!): User

  """List users with pagination"""
  users(first: Int = 20, after: String): UserConnection!
}

type Mutation {
  """Create a new user account"""
  createUser(input: CreateUserInput!): User!

  """Update user profile"""
  updateUser(id: ID!, input: UpdateUserInput!): User!

  """Delete user account"""
  deleteUser(id: ID!): Boolean!
}

input CreateUserInput {
  email: String!
  password: String!
  name: String
}

Output Deliverables

When generating API documentation, provide:

  1. OpenAPI Spec (YAML format) - Complete specification file
  2. Endpoint Summary - Quick reference table
  3. Schema Definitions - All data models
  4. Authentication Guide - How to authenticate
  5. Error Codes - Common error responses

Endpoint Summary Table

Method Path Description Auth
GET /users List all users Bearer
POST /users Create user Bearer
GET /users/{id} Get user by ID Bearer
PUT /users/{id} Update user Bearer
DELETE /users/{id} Delete user Bearer

Tips

  1. Use consistent naming: camelCase for JSON, snake_case for Python
  2. Document all status codes: Include error responses
  3. Add examples: Real example values help consumers
  4. Version your API: Include version in path or header
  5. Keep schemas DRY: Use $ref for reusable components

Recommended Agent Skills

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

brendendurham/claude-code-config

doc-intelligence

This skill orchestrates comprehensive documentation intelligence operations. Use when asked to "analyze documentation", "learn from docs", "create SOPs from documentation", "maximize documentation understanding", or any request involving systematic multi-agent documentation analysis with parallelization.

0 0
Explore
brendendurham/claude-code-config

commit-message-generator

0 0
Explore
brendendurham/claude-code-config

parallel-orchestration

This skill should be used when the user asks to "run multiple agents", "parallel review", "comprehensive analysis", "full review", "multi-agent workflow", or needs to coordinate multiple specialized agents working simultaneously. Provides patterns for launching agents in parallel and synthesizing results.

0 0
Explore
brendendurham/claude-code-config

code-explanation

0 0
Explore
brendendurham/claude-code-config

pr-review-standards

0 0
Explore
mattpocock/skills

edit-article

Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft.

111,310 9,758
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results