--- title: "AI Agent for API Documentation: Automatic OpenAPI and Readme Generation" description: "Build an AI agent that reads your codebase, extracts endpoint definitions and docstrings, and generates complete OpenAPI specs and developer-friendly README documentation automatically." canonical: https://callsphere.ai/blog/ai-agent-api-documentation-automatic-openapi-readme-generation category: "Learn Agentic AI" tags: ["API Documentation", "AI Agents", "Python", "OpenAPI", "Developer Tools"] author: "CallSphere Team" published: 2026-03-17T00:00:00.000Z updated: 2026-05-07T06:20:58.130Z --- # AI Agent for API Documentation: Automatic OpenAPI and Readme Generation > Build an AI agent that reads your codebase, extracts endpoint definitions and docstrings, and generates complete OpenAPI specs and developer-friendly README documentation automatically. ## 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. ```mermaid flowchart LR CLIENT(["Client SDK"]) GW["API Gateway auth plus rate limit"] APP["FastAPI app handlers and DI"] VAL["Pydantic validation"] SVC["Service layer 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 ``` ```python 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. ```python 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. ```python 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 ```python 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 --- Source: https://callsphere.ai/blog/ai-agent-api-documentation-automatic-openapi-readme-generation