API Documentation

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:

# 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

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:

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

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