API Documentation

Memory Operations

You have PERSISTENT MEMORY across sessions.

BEFORE starting any task:

if [ -d ~/.claude/mnemonic ]; then
    rg -i "{api_documentation}" ~/.claude/mnemonic/ --glob "*.memory.md" -l | head -5
fi

If results exist, READ the most relevant and apply that context.

AFTER completing work, if you discovered:

• A decision → capture to _semantic/decisions
• A pattern → capture to _procedural/patterns
• A learning → capture to _semantic/knowledge
• A blocker → capture to _episodic/blockers

Guidance for creating comprehensive API documentation using OpenAPI/Swagger, AsyncAPI, and manual documentation patterns.

OpenAPI/Swagger Overview

OpenAPI Specification (OAS) is the standard for describing REST APIs. Use it for:

• Auto-generating documentation portals
• Client SDK generation
• API testing and validation
• Contract-first development

Supported Versions

• OpenAPI 3.1 - Current standard, JSON Schema compatible
• OpenAPI 3.0 - Widely supported, stable
• Swagger 2.0 - Legacy, still common

Basic Structure

openapi: 3.1.0
info:
  title: API Name
  version: 1.0.0
  description: Brief API description
servers:
  - url: https://api.example.com/v1
paths:
  /resource:
    get:
      summary: Get resources
      responses:
        '200':
          description: Success

Documenting Endpoints

Required Elements

For each endpoint, document:

1. HTTP Method and Path - GET /users/{id}
2. Summary - One-line description
3. Description - Detailed explanation (when needed)
4. Parameters - Path, query, header parameters
5. Request Body - For POST/PUT/PATCH
6. Responses - All possible response codes
7. Examples - Request/response examples

Path Parameters

parameters:
  - name: userId
    in: path
    required: true
    description: Unique user identifier
    schema:
      type: string
      format: uuid
    example: "123e4567-e89b-12d3-a456-426614174000"

Query Parameters

parameters:
  - name: limit
    in: query
    required: false
    description: Maximum number of results
    schema:
      type: integer
      minimum: 1
      maximum: 100
      default: 20

Request Bodies

requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/CreateUser'
      example:
        name: "John Doe"
        email: "john@example.com"

Response Documentation

Document all response codes:

responses:
  '200':
    description: Successful response
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/User'
  '400':
    description: Invalid request parameters
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Error'
  '404':
    description: User not found
  '500':
    description: Internal server error

Schema Definitions

Component Schemas

Define reusable schemas in components:

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier
        email:
          type: string
          format: email
          description: User email address
        name:
          type: string
          description: Display name
        createdAt:
          type: string
          format: date-time

Common Patterns

Pagination:

PaginatedResponse:
  type: object
  properties:
    data:
      type: array
      items:
        $ref: '#/components/schemas/Item'
    pagination:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer

Error Response:

Error:
  type: object
  required:
    - code
    - message
  properties:
    code:
      type: string
      description: Error code
    message:
      type: string
      description: Human-readable message
    details:
      type: array
      items:
        type: object

Authentication Documentation

Security Schemes

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            read: Read access
            write: Write access

Applying Security

# Global security
security:
  - bearerAuth: []

# Per-endpoint override
paths:
  /public:
    get:
      security: []  # No auth required

AsyncAPI for Event-Driven APIs

For message-based APIs (WebSocket, MQTT, Kafka):

asyncapi: 2.6.0
info:
  title: Events API
  version: 1.0.0
channels:
  user/created:
    subscribe:
      summary: User created events
      message:
        $ref: '#/components/messages/UserCreated'
components:
  messages:
    UserCreated:
      payload:
        type: object
        properties:
          userId:
            type: string
          timestamp:
            type: string
            format: date-time

Documentation Quality Checklist

Completeness

• All endpoints documented
• All parameters described
• All response codes listed
• Authentication explained
• Rate limits documented

Accuracy

• Schemas match actual responses
• Examples are valid JSON
• Status codes are correct
• Parameter types are accurate

Usability

• Clear summaries for endpoints
• Realistic examples provided
• Error responses helpful
• Common use cases covered

Generating Documentation

From Code (Code-First)

• Extract from decorators/annotations
• Generate from type definitions
• Tools: swagger-jsdoc, FastAPI, NestJS Swagger

From Spec (Design-First)

• Write OpenAPI spec first
• Generate server stubs
• Generate client SDKs
• Tools: Swagger Codegen, OpenAPI Generator

From Language Doc Toolchains

When a project uses a language-native doc toolchain, API documentation may come from source code comments rather than OpenAPI specs. Detect and support:

When reviewing a project with both OpenAPI and a language doc toolchain:

• OpenAPI/AsyncAPI = external API contract (HTTP/event surface)
• Language doc toolchain = internal/library API surface (code-level)
• Both should be reviewed — they document different audiences
• Cross-check: HTTP endpoint docs should align with handler function doc comments

See the documentation-standards skill for detailed per-language doc comment conventions and review criteria.

Documentation Portals

• Swagger UI - Interactive API explorer
• ReDoc - Clean reference documentation
• Stoplight - Collaborative API design
• Astro Starlight - Modern documentation sites with component islands

Additional Resources

Reference Files

For detailed patterns, consult:

• references/openapi-patterns.md - Advanced OpenAPI patterns
• references/endpoint-templates.md - Copy-paste endpoint templates

Example Files

Working examples in examples/:

• petstore-openapi.yaml - Complete OpenAPI example
• events-asyncapi.yaml - AsyncAPI example