API Documentation for AI Agent Services: OpenAPI, Redoc, and Interactive Playgrounds

Why Documentation Matters More for AI Agent APIs

AI agent APIs serve two audiences that traditional APIs often do not: other AI agents and developers building agent integrations. Agents need machine-readable specifications with precise type definitions and example payloads to generate correct tool-call schemas. Developers need clear examples showing the multi-step workflows that agent interactions require — creating sessions, sending messages, handling tool calls, and closing conversations.

Poor documentation leads to integration failures, support tickets, and developers reverse-engineering your API from network traces. Good documentation lets both humans and agents self-serve.

OpenAPI Specification from FastAPI

FastAPI generates an OpenAPI 3.1 specification automatically from your route definitions and Pydantic models. The key is enriching your models and endpoints with descriptions, examples, and proper metadata:

flowchart LR
    CLIENT(["Client SDK"])
    GW["API Gateway<br/>auth plus rate limit"]
    APP["FastAPI app<br/>handlers and DI"]
    VAL["Pydantic validation"]
    SVC["Service layer<br/>business logic"]
    DB[(Database)]
    QUEUE[(Background queue)]
    OBS[(Tracing)]
    CLIENT --> GW --> APP --> VAL --> SVC
    SVC --> DB
    SVC --> QUEUE
    SVC --> OBS
    SVC --> CLIENT
    style GW fill:#4f46e5,stroke:#4338ca,color:#fff
    style APP fill:#f59e0b,stroke:#d97706,color:#1f2937
    style DB fill:#ede9fe,stroke:#7c3aed,color:#1e1b4b

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field
from typing import Optional

app = FastAPI(
    title="AI Agent API",
    description="Unified API for managing AI agent conversations, "
                "tool calls, and task execution.",
    version="2.1.0",
    contact={"name": "Agent Platform Team", "email": "[email protected]"},
    license_info={"name": "MIT"},
)

class ConversationCreate(BaseModel):
    """Create a new conversation session with an AI agent."""
    agent_id: str = Field(
        ...,
        description="The unique identifier of the agent to converse with.",
        examples=["agent-support-v3"],
    )
    system_prompt: Optional[str] = Field(
        None,
        description="Optional override for the agent system prompt.",
        examples=["You are a billing specialist. Be concise."],
    )
    parameters: dict = Field(
        default_factory=dict,
        description="Agent-specific parameters like temperature or max_tokens.",
        examples=[{"temperature": 0.7, "max_tokens": 1024}],
    )

    model_config = {
        "json_schema_extra": {
            "examples": [
                {
                    "agent_id": "agent-support-v3",
                    "system_prompt": "You are a billing specialist.",
                    "parameters": {"temperature": 0.7},
                }
            ]
        }
    }

class ConversationResponse(BaseModel):
    """A conversation session resource."""
    id: str = Field(..., examples=["conv_8f3a2b1c"])
    agent_id: str = Field(..., examples=["agent-support-v3"])
    created_at: str = Field(..., examples=["2026-03-17T10:30:00Z"])
    message_count: int = Field(..., examples=[0])
    status: str = Field(..., examples=["active"])

Every field has a description and at least one example. This metadata flows directly into the OpenAPI spec, making the generated documentation immediately useful without manual editing.

Documenting Endpoints with Rich Metadata

Use FastAPI's endpoint parameters to add response descriptions, status codes, and tags:

@app.post(
    "/v1/conversations",
    response_model=ConversationResponse,
    status_code=201,
    tags=["Conversations"],
    summary="Create a conversation",
    description="Start a new conversation session with the specified agent. "
                "Returns a conversation ID used for subsequent message exchanges.",
    responses={
        201: {
            "description": "Conversation created successfully.",
            "content": {
                "application/json": {
                    "example": {
                        "id": "conv_8f3a2b1c",
                        "agent_id": "agent-support-v3",
                        "created_at": "2026-03-17T10:30:00Z",
                        "message_count": 0,
                        "status": "active",
                    }
                }
            },
        },
        422: {"description": "Invalid request body."},
        429: {"description": "Rate limit exceeded. Check Retry-After header."},
    },
)
async def create_conversation(body: ConversationCreate):
    pass  # Implementation here

@app.get(
    "/v1/conversations",
    tags=["Conversations"],
    summary="List conversations",
    description="Retrieve a paginated list of conversations. "
                "Use cursor-based pagination with the after parameter.",
)
async def list_conversations(
    limit: int = Query(20, ge=1, le=100, description="Number of results per page."),
    after: Optional[str] = Query(None, description="Cursor for pagination."),
    agent_id: Optional[str] = Query(None, description="Filter by agent ID."),
):
    pass

Custom Documentation Pages

FastAPI serves Swagger UI at /docs and Redoc at /redoc by default. Customize them for a better developer experience:

from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html

@app.get("/docs", include_in_schema=False)
async def custom_swagger():
    return get_swagger_ui_html(
        openapi_url="/openapi.json",
        title="AI Agent API - Interactive Docs",
        swagger_ui_parameters={
            "persistAuthorization": True,
            "displayRequestDuration": True,
            "filter": True,
            "tryItOutEnabled": True,
        },
    )

@app.get("/redoc", include_in_schema=False)
async def custom_redoc():
    return get_redoc_html(
        openapi_url="/openapi.json",
        title="AI Agent API - Reference",
    )

The persistAuthorization parameter remembers the API key across page reloads, which is essential when testing multi-step agent workflows.

Exporting the OpenAPI Spec

Export the spec as a static JSON file for SDK generation and external consumers:

import json

@app.get("/openapi.json", include_in_schema=False)
async def get_openapi_spec():
    return app.openapi()

# Generate spec at build time
if __name__ == "__main__":
    spec = app.openapi()
    with open("openapi.json", "w") as f:
        json.dump(spec, f, indent=2)
    print(f"Spec generated: {len(spec['paths'])} endpoints documented")

SDK Generation from OpenAPI

With a clean OpenAPI spec, you can auto-generate client SDKs. Use openapi-generator to produce typed clients:

# Generate Python SDK
# openapi-generator-cli generate -i openapi.json -g python -o sdk/python

# Generate TypeScript SDK
# openapi-generator-cli generate -i openapi.json -g typescript-fetch -o sdk/typescript

# The generated client handles serialization, auth headers, and error types
# Example usage of the generated Python client:
from agent_api_client import AgentApi, ConversationCreate

client = AgentApi(base_url="https://api.agents.example.com")
client.set_api_key("sk-agent-abc123")

conversation = client.create_conversation(
    ConversationCreate(agent_id="agent-support-v3")
)

Workflow Documentation with Markdown

OpenAPI describes individual endpoints but not multi-step workflows. Add workflow guides as markdown in the spec description:

WORKFLOW_DOCS = """
## Quick Start

### 1. Create a conversation
\'POST /v1/conversations\' with your agent ID.

### 2. Send messages
\'POST /v1/conversations/{id}/messages\' with role and content.

### 3. Handle tool calls
If the agent returns tool_calls, execute each tool and submit results
via \'POST /v1/conversations/{id}/tool-results\'.

### 4. Close the conversation
\'DELETE /v1/conversations/{id}\' when finished.
"""

app.description = WORKFLOW_DOCS

FAQ

How do I keep API docs in sync with the actual implementation?

With FastAPI, the docs are always in sync because they are generated from the code. The OpenAPI spec is derived from your route decorators and Pydantic models at runtime. If you change a field type or add an endpoint, the docs update automatically. Add a CI check that exports the spec and fails if it differs from the committed version.

Should I include error response schemas in the documentation?

Yes. Document every error status code your API returns with its response body schema. AI agent developers need to program their error handling logic against your documented error formats. Include the error code, message structure, and any retry guidance directly in the OpenAPI response definitions.

How do I document streaming endpoints in OpenAPI?

OpenAPI has limited native support for streaming. Document streaming endpoints with a description explaining the SSE format, include example event payloads in the description field, and add a note about the text/event-stream content type. Consider maintaining a separate streaming reference page linked from the endpoint description.

---

#APIDocumentation #OpenAPI #AIAgents #FastAPI #DeveloperExperience #AgenticAI #LearnAI #AIEngineering