MODULE 07

API Documentation
That AI Can Read

Your beautiful API docs are designed for humans. Learn how to provide machine-readable documentation that AI agents can actually parse and understand.

~8 min read
Intermediate
Documentation
Full Step-by-Step Documentation ~20 min

đŸŽ¯ The Documentation Gap

Modern API documentation tools like Swagger UI, Redoc, and Stoplight create beautiful, interactive docs for human developers. But when an AI agent needs to understand your API, it can't click buttons or hover over tooltips.

AI agents need structured, machine-readable specifications they can parse and reason about. The good news: you probably already have this. You just need to expose it correctly.

📚 Documentation Formats Compared

📋

OpenAPI/Swagger

Industry standard. JSON or YAML. Most AI models understand it natively.

Best for AI
📘

JSON Schema

Defines data structures. Often embedded in OpenAPI specs.

Good
📄

Markdown/HTML

Human-readable but requires parsing. Prone to hallucination.

Poor for AI

✅ AI-Readable Documentation Checklist

1

Expose OpenAPI Spec at Known URL

Serve your spec at /openapi.json or /api/docs/openapi.json. AI can fetch and parse it directly.

2

Include Complete Request/Response Examples

Every endpoint should have example payloads. AI uses these to understand expected formats.

3

Document All Error Codes

List every possible error response with codes and messages. AI needs to handle errors gracefully.

4

Describe Parameters Thoroughly

Include type, format, constraints, and description for every parameter. Vague docs cause hallucinations.

5

Use Semantic Descriptions

Write descriptions that explain business logic: "Returns orders from the last 30 days" not "Gets orders".

⚖ī¸ Good vs Poor Documentation

❌

Poor (AI will struggle)

get:
  summary: Get customers
  responses:
    200:
      description: Success
✓

Good (AI can understand)

get:
  summary: List active customers
  description: Returns paginated
    list of customers with
    active subscriptions
  parameters:
   - name: limit
      in: query
      schema:
        type: integer
        default: 100
        maximum: 500
  responses:
    200:
      description: Customer list
      content:
        application/json:
          schema:
            $ref: '#/Customer'
          example:
            resource: [...]
            meta: {...}

đŸ’ģ DreamFactory Auto-Generated Docs

DreamFactory automatically generates complete OpenAPI specifications for all your database APIs. Access them at:

URLs 
# Full OpenAPI spec (JSON)
GET /api/v2/api_docs

# Service-specific spec
GET /api/v2/{service_name}/api_docs

# Interactive Swagger UI
GET /api/v2/api_docs/ui

# Schema for specific table
GET /api/v2/{service}/_schema/{table}

🔧 Enriching Your OpenAPI Spec

YAML 
# Add AI-helpful metadata to your OpenAPI spec
paths:
  /api/v2/db/_table/orders:
    get:
      operationId: listOrders
      summary: List customer orders
      description: |
        Returns a paginated list of orders.
        Default limit is 100 records.
        Use filter parameter for queries.
        Results sorted by created_at DESC.
      x-ai-hints:
        common-filters:
         - "status=pending"
         - "customer_id={id}"
         - "created_at>2024-01-01"
        typical-usage: "Fetch recent orders for dashboard"
        related-endpoints:
         - "/api/v2/db/_table/customers"
         - "/api/v2/db/_table/order_items"
✓

Custom Extensions

OpenAPI allows x- prefixed extensions. Use these to add AI-specific hints that won't break standard tooling.

💡 Best Practices

⚠ī¸

Keep Specs Updated

Stale documentation causes AI to call non-existent endpoints. Auto-generate specs from code when possible. DreamFactory does this automatically.

ℹī¸

Include Constraints

Document minimum/maximum values, required fields, enum options, and regex patterns. AI uses these to validate before calling.

✓

Test with AI

Ask an AI to read your OpenAPI spec and describe what the API does. If it gets confused, your docs need work.

Ready to implement? Get the complete step-by-step guide with code examples, screenshots, and troubleshooting tips.

Full Step-by-Step Documentation ~20 min