AI Agent for API Documentation: Automatic OpenAPI and Readme Generation

The Documentation Problem

API documentation goes stale the moment it is written. Endpoints change, request bodies gain new fields, response schemas evolve, but the docs stay frozen in time. An AI documentation agent solves this by reading the actual source code and generating accurate, up-to-date documentation on every change.

The agent parses your route definitions, extracts type information from models and schemas, and produces both a machine-readable OpenAPI spec and a human-friendly developer guide.

Extracting Routes from Source Code

The first step is parsing your codebase to find all API endpoint definitions. For a FastAPI application, this means finding decorated route functions and their parameters.

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

import ast
import os
from dataclasses import dataclass, field

@dataclass
class EndpointInfo:
    method: str
    path: str
    function_name: str
    docstring: str | None
    parameters: list[dict]
    request_body: str | None
    response_model: str | None
    file_path: str

class CodeParser:
    def __init__(self, source_dir: str):
        self.source_dir = source_dir

    def find_endpoints(self) -> list[EndpointInfo]:
        endpoints = []
        for root, _, files in os.walk(self.source_dir):
            for fname in files:
                if not fname.endswith(".py"):
                    continue
                path = os.path.join(root, fname)
                with open(path) as f:
                    tree = ast.parse(f.read())
                endpoints.extend(self._extract_routes(tree, path))
        return endpoints

    def _extract_routes(
        self, tree: ast.Module, file_path: str
    ) -> list[EndpointInfo]:
        endpoints = []
        for node in ast.walk(tree):
            if not isinstance(node, ast.AsyncFunctionDef | ast.FunctionDef):
                continue
            for decorator in node.decorator_list:
                route_info = self._parse_decorator(decorator)
                if route_info:
                    endpoints.append(EndpointInfo(
                        method=route_info["method"],
                        path=route_info["path"],
                        function_name=node.name,
                        docstring=ast.get_docstring(node),
                        parameters=self._extract_params(node),
                        request_body=self._find_body_model(node),
                        response_model=route_info.get("response_model"),
                        file_path=file_path,
                    ))
        return endpoints

The parser walks the AST of every Python file, looking for functions with route decorators. This approach is more reliable than regex because it handles multiline decorators and complex parameter definitions correctly.

Generating the OpenAPI Specification

With structured endpoint information, the agent uses the LLM to produce a complete OpenAPI 3.0 spec, filling in descriptions, examples, and response schemas that the code alone cannot provide.

import json
from openai import OpenAI

client = OpenAI()

class DocumentationAgent:
    def __init__(self, source_dir: str, model: str = "gpt-4o"):
        self.parser = CodeParser(source_dir)
        self.model = model

    def generate_openapi(self, api_title: str, version: str) -> dict:
        endpoints = self.parser.find_endpoints()
        endpoint_descriptions = []
        for ep in endpoints:
            desc = (
                f"{ep.method.upper()} {ep.path}\n"
                f"Function: {ep.function_name}\n"
                f"Docstring: {ep.docstring or 'None'}\n"
                f"Parameters: {ep.parameters}\n"
                f"Request body model: {ep.request_body or 'None'}\n"
                f"Response model: {ep.response_model or 'None'}"
            )
            endpoint_descriptions.append(desc)

        system_prompt = """Generate a complete OpenAPI 3.0.3 specification
as a JSON object from the provided endpoint information.

For each endpoint include:
- Summary and description
- Request parameters with types and examples
- Request body schema if applicable
- Response schemas for 200, 400, 404, 500
- Realistic example values for all fields

Output ONLY valid JSON."""

        response = client.chat.completions.create(
            model=self.model,
            messages=[
                {"role": "system", "content": system_prompt},
                {"role": "user", "content": (
                    f"API: {api_title} v{version}\n\n"
                    + "\n---\n".join(endpoint_descriptions)
                )},
            ],
            temperature=0,
            response_format={"type": "json_object"},
        )
        return json.loads(response.choices[0].message.content)

Generating a Developer README

Machine-readable specs are useful for tooling, but developers also need a readable guide with examples. The agent generates this from the same endpoint data.

def generate_readme(self, api_title: str) -> str:
    endpoints = self.parser.find_endpoints()
    endpoint_text = "\n---\n".join(
        f"{ep.method.upper()} {ep.path}: {ep.docstring or ep.function_name}"
        for ep in endpoints
    )

    system_prompt = f"""Generate developer-friendly API documentation
for {api_title} in Markdown format.

Include for each endpoint:
- Description of what it does
- curl example with realistic data
- Example response body
- Error codes and their meanings

Start with a quick-start section showing authentication
and a basic request. Group endpoints by resource."""

    response = client.chat.completions.create(
        model=self.model,
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": endpoint_text},
        ],
        temperature=0.3,
    )
    return response.choices[0].message.content

Running the Agent

agent = DocumentationAgent("./app")
spec = agent.generate_openapi("My API", "1.0.0")

with open("openapi.json", "w") as f:
    json.dump(spec, f, indent=2)

readme = agent.generate_readme("My API")
with open("API_DOCS.md", "w") as f:
    f.write(readme)

print(f"Generated docs for {len(agent.parser.find_endpoints())} endpoints")

FAQ

How do I keep the documentation in sync with code changes?

Run the agent as a CI step on every pull request. Compare the newly generated spec against the committed spec. If they differ, either auto-commit the updated docs or fail the PR with a message indicating documentation is out of date.

Can the agent document request and response types accurately without running the app?

For typed frameworks like FastAPI with Pydantic models, the AST parser can extract model definitions and their fields. For untyped frameworks, the LLM infers types from docstrings, parameter names, and usage patterns. The accuracy improves significantly when your code includes type annotations.

How do I handle private or internal endpoints that should not appear in public docs?

Add a filtering step that checks for a custom decorator or docstring marker like @internal or # private. The code parser skips endpoints with these markers before passing data to the LLM.

---

#APIDocumentation #AIAgents #Python #OpenAPI #DeveloperTools #AgenticAI #LearnAI #AIEngineering