By Pindi Sahota · Last updated: 2026-06-07
This page contains affiliate links. If you purchase through them, I may earn a commission at no extra cost to you.
Claude for Writing API Documentation (2026 Guide)
Last updated: 2026-06-07
Claude API documentation generation turns one of the most tedious parts of software development into a fast, largely automated task. Give Claude your route definitions, function signatures, or existing code, and it produces complete, accurate documentation: OpenAPI 3.1 YAML specs, Markdown endpoint references, inline docstrings, README sections, and multi-language code examples. The output follows documentation best practices — request/response schemas, error codes, authentication details, and example payloads included. This guide covers every documentation format, the exact prompts that produce the best output, and a complete OpenAPI spec example generated from a real API.
Why Claude Excels at API Documentation
API documentation has two hard parts: completeness (covering every endpoint, parameter, and error case) and accuracy (matching what the code actually does). Human-written docs suffer from both — sections get skipped when deadlines hit, and docs drift from the implementation over time. Claude handles both by reading the actual source code:
- Completeness — Claude generates docs for every route, every query parameter, every response code it sees in the code.
- Accuracy — Claude reads your Pydantic models, TypeScript interfaces, or function signatures and uses them directly for schema definitions.
- Consistency — every endpoint follows the same format, tone, and detail level.
- Multi-language examples — Claude generates curl, Python, JavaScript, and other language examples for each endpoint automatically.
How to Write API Documentation with Claude — Step by Step
Step 1: Choose Your Documentation Type
Decide what you need before prompting:
| Documentation type | Best for | Format |
|---|---|---|
| OpenAPI 3.1 spec | Public APIs, SDK generation, Swagger UI | YAML |
| README / Quickstart | GitHub repos, developer onboarding | Markdown |
| Endpoint reference | Developer portal pages | Markdown |
| Inline docstrings | Code maintainability, IDE tooltips | Language-native |
| Code examples | SDK docs, tutorials | Code blocks |
Step 2: Prepare Your Source Material
Give Claude the most direct source of truth available:
- For existing APIs — paste your route definitions and request/response models
- For new APIs — describe the endpoints in plain English
- For Claude Code — no preparation needed; Claude reads your files directly
Step 3: Generate an OpenAPI Spec
Paste your FastAPI (or Express, or Rails) route code and ask:
` Generate a complete OpenAPI 3.1 YAML spec from these FastAPI routes. Include all schemas, required fields, response codes (200, 400, 401, 404, 500), example values, and Bearer token authentication. Use the function docstrings as the endpoint descriptions. `
Step 4: Generate a README Section
For a developer-facing README:
` Write a "Getting Started" README section for this REST API. Cover: authentication (Bearer token), base URL, rate limits (100 req/min), and show a complete curl example for each endpoint. Use markdown with code blocks. `
Step 5: Generate Docstrings in Bulk with Claude Code
In a multi-file project, Claude Code can add docstrings to all undocumented functions:
`bash claude
Add Google-style docstrings to every function in the services/
directory that currently lacks one. Use the function logic and existing type hints to infer the parameter and return descriptions. `
Documentation Types and Prompt Templates
OpenAPI 3.1 YAML — Complete Example
Below is a Claude-generated OpenAPI spec for a simple user authentication API:
`yaml openapi: 3.1.0 info: title: User Auth API version: 1.0.0 description: Handles user registration, login, and token management.
servers: - url: https://api.example.com/v1 description: Production - url: https://staging-api.example.com/v1 description: Staging
security: - BearerAuth: []
paths: /auth/register: post: summary: Register a new user operationId: registerUser security: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RegisterRequest' example: email: alice@example.com password: "S3cure!Pass" displayname: Alice Johnson responses: '201': description: User created successfully content: application/json: schema: $ref: '#/components/schemas/AuthResponse' '409': description: Email already registered content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: emailalready_registered message: An account with this email address already exists.
/auth/login: post: summary: Log in and receive access token operationId: loginUser security: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LoginRequest' responses: '200': description: Login successful content: application/json: schema: $ref: '#/components/schemas/AuthResponse' '401': description: Invalid credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse'
/auth/refresh: post: summary: Exchange a refresh token for a new access token operationId: refreshToken requestBody: required: true content: application/json: schema: type: object required: [refreshtoken] properties: refreshtoken: type: string description: Long-lived refresh token issued at login. responses: '200': description: New access token issued content: application/json: schema: $ref: '#/components/schemas/AuthResponse' '401': description: Invalid or expired refresh token
/users/me: get: summary: Get the authenticated user's profile operationId: getCurrentUser responses: '200': description: User profile content: application/json: schema: $ref: '#/components/schemas/UserProfile' '401': description: Missing or invalid token
components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT
schemas: RegisterRequest: type: object required: [email, password, displayname] properties: email: type: string format: email password: type: string minLength: 8 displayname: type: string minLength: 2 maxLength: 60
LoginRequest: type: object required: [email, password] properties: email: type: string format: email password: type: string
AuthResponse: type: object properties: accesstoken: type: string description: Short-lived JWT (expires 15 minutes). refreshtoken: type: string description: Long-lived token for acquiring new access tokens (expires 30 days). tokentype: type: string enum: [bearer] expiresin: type: integer example: 900
UserProfile: type: object properties: id: type: string format: uuid email: type: string format: email displayname: type: string createdat: type: string format: date-time
ErrorResponse: type: object required: [error, message] properties: error: type: string description: Machine-readable error code. message: type: string description: Human-readable error description. `
Generating Python Docstrings
Prompt:
` Add comprehensive Google-style docstrings to these functions. Infer the parameter types and meanings from the code and type hints. Include: summary, Args, Returns, Raises sections. `
Before: `python def createinvoice(customerid, lineitems, duedays=30): if not lineitems: raise ValueError("lineitems cannot be empty") total = sum(item["amount"] for item in line_items) ... `
After (Claude-generated docstring): `python def createinvoice(customerid: str, lineitems: list[dict], duedays: int = 30) -> Invoice: """Create a new invoice for a customer.
Calculates the total from the provided line items and sets the due date relative to today based on due_days. Saves the invoice to the database and returns the created Invoice object.
Args: customerid: The UUID of the customer to invoice. lineitems: List of line item dicts, each with keys: - description (str): Human-readable item description. - amount (float): Amount in the account currency, must be > 0. - quantity (int): Number of units, default 1. due_days: Number of days from today until payment is due. Defaults to 30.
Returns: The created Invoice object with id, total, and due_date populated.
Raises: ValueError: If lineitems is empty or any amount is not positive. CustomerNotFoundError: If no customer exists with the given customerid. """ `
Generating Endpoint Reference Docs (Markdown)
Prompt:
` Write Markdown endpoint reference documentation for these routes. For each endpoint include: HTTP method and path, description, authentication requirements, request parameters (path, query, body), response schema, error codes, and a curl example. `
Claude generates structured Markdown that can go directly into a docs site, GitHub wiki, or developer portal.
Tips for Best Results
Paste schemas alongside routes. If your routes reference Pydantic models or TypeScript interfaces, include those too. Claude generates accurate schemas from them rather than guessing field types.
Ask for error documentation explicitly. Documentation often skips the error cases. Add "document all error responses including status codes, error codes, and when they occur" to your prompt.
Request multi-language examples. "Include code examples in curl, Python (using httpx), and JavaScript (using fetch)" gets you examples your users actually want.
Use Claude Code for living documentation. Set up a docs:generate script that runs Claude Code against your routes directory and regenerates the OpenAPI spec. Documentation stays in sync with the code automatically.