API Documenter

API documentation specialist generating OpenAPI specifications and developer-friendly API references.

Quick Reference

Property	Value
Domain	Documentation
FORGE Stage	5 (VERIFY)
Version	1.0.0
Output Types	OpenAPI JSON/YAML

Overview

Use this agent when you need to:

Generate OpenAPI 3.1 specifications from code
Convert Zod schemas to JSON Schema
Document REST API endpoints
Create realistic request/response examples
Keep API docs synchronized with implementation
Validate OpenAPI specs for correctness

The API Documenter extracts API structure from Hono route handlers and Zod schemas, producing comprehensive OpenAPI specifications.

Core Capabilities

OpenAPI Generation

Create OpenAPI 3.1 specifications from Hono APIs

Schema Conversion

Convert Zod schemas to JSON Schema for OpenAPI

Example Generation

Create realistic request/response examples

Documentation Sync

Keep specs in sync with code implementation

When to Use

API endpoints implemented in Hono backend

Zod schemas defined in so1-shared

Need OpenAPI spec for API reference docs

Integrating with API tools (Postman, Insomnia)

Validating API design and consistency

Generating client SDKs from OpenAPI

Usage Examples

Complete OpenAPI Spec
Zod to JSON Schema
Error Responses

Generate a full OpenAPI 3.1 specification:

openapi: 3.1.0
info:
  title: SO1 Control Plane API
  version: 1.0.0
  description: |
    The SO1 API provides programmatic access to manage workflows,
    executions, and integrations.
    
    ## Authentication
    All requests require API key in Authorization header:

Authorization: Bearer sk_live_xxxxxxxxxxxx

## Rate Limiting
100 requests per minute per API key
contact:
email: support@so1.io

servers:
- url: https://api.so1.io
description: Production
- url: https://api-staging.so1.io
description: Staging

security:
- bearerAuth: []

tags:
- name: Workflows
description: Manage automation workflows
- name: Executions
description: View workflow executions

paths:
/api/v1/workflows:
get:
  operationId: listWorkflows
  summary: List workflows
  tags: [Workflows]
  parameters:
    - name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1
    - name: status
      in: query
      schema:
        type: string
        enum: [draft, active, inactive]
  responses:
    '200':
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WorkflowList'
          example:
            success: true
            data:
              items:
                - id: wf_abc123
                  name: Daily Report
                  status: active
              pagination:
                page: 1
                total: 1

post:
  operationId: createWorkflow
  summary: Create workflow
  tags: [Workflows]
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/CreateWorkflowInput'
        example:
          name: Daily Report
          triggerType: schedule
  responses:
    '201':
      description: Created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Workflow'

components:
securitySchemes:
bearerAuth:
  type: http
  scheme: bearer
  bearerFormat: API Key

schemas:
Workflow:
  type: object
  required: [id, name, status]
  properties:
    id:
      type: string
      pattern: ^wf_[a-zA-Z0-9]+$
    name:
      type: string
      minLength: 1
      maxLength: 100
    status:
      type: string
      enum: [draft, active, inactive]

Result: Complete OpenAPI spec ready for Mintlify, Swagger UI, or SDK generation.

Convert Zod schemas to OpenAPI-compatible JSON Schema:

// Source: Zod schema in so1-shared
import { z } from 'zod';

export const WorkflowSchema = z.object({
  id: z.string().regex(/^wf_[a-zA-Z0-9]+$/),
  name: z.string().min(1).max(100),
  description: z.string().max(500).optional(),
  status: z.enum(['draft', 'active', 'inactive']),
  triggerType: z.enum(['manual', 'webhook', 'schedule']),
  createdAt: z.coerce.date(),
  updatedAt: z.coerce.date(),
});

// Generated: JSON Schema in OpenAPI
{
  "type": "object",
  "required": ["id", "name", "status", "triggerType", "createdAt", "updatedAt"],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^wf_[a-zA-Z0-9]+$",
      "description": "Unique workflow identifier"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Workflow display name"
    },
    "description": {
      "type": "string",
      "maxLength": 500,
      "description": "Optional description"
    },
    "status": {
      "type": "string",
      "enum": ["draft", "active", "inactive"],
      "description": "Current status"
    },
    "triggerType": {
      "type": "string",
      "enum": ["manual", "webhook", "schedule"]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}

Result: Type-safe schemas automatically converted to OpenAPI format.

Document comprehensive error responses:

responses:
  BadRequest:
    description: Bad request - validation failed
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'
        examples:
          validation_error:
            summary: Validation error
            value:
              success: false
              error:
                code: VALIDATION_ERROR
                message: Invalid request body
                details:
                  field: name
                  issue: Required field missing
          
          invalid_cron:
            summary: Invalid cron expression
            value:
              success: false
              error:
                code: VALIDATION_ERROR
                message: Invalid cron expression
                details:
                  field: triggerConfig.cron
                  value: "invalid"

  Unauthorized:
    description: Missing or invalid API key
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'
        example:
          success: false
          error:
            code: UNAUTHORIZED
            message: Invalid or missing API key

  NotFound:
    description: Resource not found
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'
        example:
          success: false
          error:
            code: NOT_FOUND
            message: Workflow not found

Result: Complete error documentation with multiple examples per error type.

Outputs

Zod Type Mappings

Zod Type	OpenAPI Type	Notes
`z.string()`	`{ type: "string" }`
`z.number()`	`{ type: "number" }`
`z.boolean()`	`{ type: "boolean" }`
`z.array(T)`	`{ type: "array", items: T }`
`z.object({...})`	`{ type: "object", properties: {...} }`
`z.enum([...])`	`{ type: "string", enum: [...] }`
`z.optional()`	Remove from `required` array
`z.nullable()`	Add `null` to type union
`z.coerce.date()`	`{ type: "string", format: "date-time" }`
`z.min(n)` / `z.max(n)`	`minLength` / `maxLength`	For strings
`z.regex(pattern)`	`{ pattern: "..." }`

OpenAPI Structure

openapi: 3.1.0
info:                    # API metadata
  title: ...
  version: ...
  description: ...
servers:                 # API base URLs
  - url: ...
security:                # Global auth requirements
  - bearerAuth: []
tags:                    # Endpoint groupings
  - name: ...
paths:                   # API endpoints
  /api/v1/resource:
    get: ...
    post: ...
components:              # Reusable components
  securitySchemes: ...
  schemas: ...
  responses: ...
  parameters: ...

FORGE Gate Compliance

Entry Gates

API endpoints implemented

All Hono route handlers must be implemented and working.

Zod schemas defined

Request/response schemas must be defined in so1-shared package.

Authentication documented

Auth middleware and patterns must be documented.

Exit Gates

OpenAPI spec generated

Complete openapi.json or openapi.yaml file created.

All endpoints documented

Every route has summary, description, parameters, and responses.

Examples provided

Request and response examples for success and error cases.

Schema validation passing

Spec validates against OpenAPI 3.1 schema (use spectral or openapi-lint).

Integration Points

Veritas Prompts

Consumed Prompts
Produced Prompts

Prompt ID	Purpose
`vrt-k1l2m3n4`	API documentation standards (RESTful conventions, naming)
`vrt-o5p6q7r8`	OpenAPI best practices (schema design, examples)

Novel API patterns discovered during documentation:

{
  "id": "vrt-api-pattern-001",
  "category": "fragment",
  "status": "draft",
  "content": "Standardized error envelope pattern",
  "outputPath": "veritas/agent-prompts/documentation/api-pattern-001.json"
}

Agent	Relationship
Hono Backend	Source of API implementations
TypeScript Shared	Source of Zod schemas
Mintlify Author	Consumes OpenAPI for docs site

Source Files

View Agent Source

Repository: so1-io/so1-agents
Path: agents/documentation/api-documenter.md
Version: 1.0.0

Validation and Tools

Validate OpenAPI Spec

# Using Spectral (recommended)
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

# Using openapi-lint
npm install -g @redocly/cli
redocly lint openapi.yaml

Generate from Spec

# Generate TypeScript client
npx openapi-typescript openapi.yaml -o api-types.ts

# Generate Postman collection
npx openapi-to-postmanv2 -s openapi.yaml -o postman-collection.json

# Preview in Swagger UI
npx swagger-ui-watcher openapi.yaml

Next Steps:

Agents Overview

Orchestration

Automation

Engineering

DevOps

Documentation

Prompts

Incident

API Documenter

API Documenter

Quick Reference

Overview

Core Capabilities

OpenAPI Generation

Schema Conversion

Example Generation

Documentation Sync

When to Use

Usage Examples

Outputs

Zod Type Mappings

OpenAPI Structure

FORGE Gate Compliance

Entry Gates

Exit Gates

Integration Points

Veritas Prompts

Source Files

View Agent Source

Validation and Tools

Validate OpenAPI Spec

Generate from Spec

Agents Overview

Orchestration

Automation

Engineering

DevOps

Documentation

Prompts

Incident

​API Documenter

​Quick Reference

​Overview

​Core Capabilities

OpenAPI Generation

Schema Conversion

Example Generation

Documentation Sync

​When to Use

​Usage Examples

​Outputs

​Zod Type Mappings

​OpenAPI Structure

​FORGE Gate Compliance

​Entry Gates

​Exit Gates

​Integration Points

​Veritas Prompts

​Related Agents

​Source Files

View Agent Source

​Validation and Tools

​Validate OpenAPI Spec

​Generate from Spec

API Documenter

Quick Reference

Overview

Core Capabilities

When to Use

Usage Examples

Outputs

Zod Type Mappings

OpenAPI Structure

FORGE Gate Compliance

Entry Gates

Exit Gates

Integration Points

Veritas Prompts

Related Agents

Source Files

Validation and Tools

Validate OpenAPI Spec

Generate from Spec