API Documentation

What You’ll Learn

• How to prompt Claude to generate complete, structured API documentation from code or a description
• Techniques for producing OpenAPI/Swagger specs, README endpoint sections, and developer guides
• How to use Claude to keep documentation consistent and update it as your API evolves

The Use Case

Documentation is the part of API development that almost every team falls behind on. The code ships; the docs lag. New endpoints get added without entries. Parameters change but the docs don’t. Error codes multiply without explanation. Eventually, your API consumers — internal or external — are reverse-engineering your API from trial and error instead of consulting documentation that should exist.

Claude dramatically lowers the friction of writing API documentation because it understands the intent behind code and can translate it into structured, human-readable prose. You paste a route handler, a controller, or even just a description of what an endpoint does, and Claude produces documentation that covers the endpoint’s purpose, all parameters with types and descriptions, example requests and responses, and the error cases a caller should handle.

This is especially valuable for teams that build APIs faster than they write docs, teams onboarding new developers who need to understand existing endpoints quickly, and teams that need to produce OpenAPI specifications for tooling like Swagger UI, Postman collections, or SDK generation.

Step-by-Step Guide

Step 1: Decide your documentation format

API documentation comes in several formats with different purposes:

• OpenAPI 3.x YAML/JSON — Machine-readable spec for tooling (Swagger UI, code generation, Postman import)
• Markdown endpoint reference — Human-readable docs for a README or docs site
• Inline code comments — JSDoc, Python docstrings, Go doc comments for IDE integration
• Developer guide prose — Narrative documentation explaining authentication, pagination, rate limiting

Tell Claude which format you need. Each requires different structure and detail.

Step 2: Provide the source material

Give Claude one of the following starting points:

Option A — Paste the route handler or controller code: This is the most reliable approach. Claude can read the actual implementation and document what it does, including inferred behavior like which fields are optional.

Option B — Describe the endpoint in plain English: If you don’t have code yet (or it’s in a language Claude would struggle with), describe the endpoint: method, path, authentication requirements, what each parameter does, what success looks like, and what errors can occur.

Option C — Paste an existing incomplete doc and ask for expansion: “Here’s a partial endpoint description. Expand it to be complete — add missing parameters, fill in the error table, and add a request/response example.”

Step 3: Specify what “complete” means for your context

Different audiences need different levels of detail. Tell Claude:

• Who will read this? (External developers, internal engineers, junior devs)
• Does it need curl examples? JavaScript fetch? Python requests?
• Should error codes be documented as a table?
• Does it need authentication instructions?

Example: “This is public-facing documentation for external developers. Include: endpoint description, all path/query/body parameters with types and whether they’re required, a curl example, a JSON response example, and a table of all possible HTTP error codes with explanations.”

Step 4: Generate an OpenAPI spec

For machine-readable specs, ask Claude directly:

“Generate an OpenAPI 3.0 spec in YAML for this endpoint.”

Provide the route handler and Claude will produce a properly structured spec with paths, operationId, parameters, requestBody schema, and response schemas. You can then paste this into Swagger Editor to validate it, or drop it into your existing spec file.

Step 5: Maintain documentation as your API changes

When an endpoint changes, paste the updated code and the old documentation side by side:

“Here’s the updated route handler and the existing documentation. Update the docs to reflect the changes — new parameter sort_by, changed default for limit from 20 to 50, and new 422 error case.”

This incremental update workflow keeps docs in sync without rewriting from scratch.

Prompt Template

Please generate API documentation for the following endpoint.

Format: [OpenAPI 3.0 YAML / Markdown reference / JSDoc comment / etc.]
Audience: [Internal engineers / External developers / etc.]

Endpoint details:
[PASTE ROUTE HANDLER CODE, OR describe the following:]
- Method: [GET / POST / PUT / DELETE / etc.]
- Path: [e.g., /api/v1/users/{id}]
- Authentication: [Bearer token / API key / none]
- Description: [What this endpoint does]
- Path parameters: [list with types]
- Query parameters: [list with types, required/optional, defaults]
- Request body: [JSON schema or field descriptions]
- Success response: [status code, body structure]
- Error responses: [status codes and when they occur]

Include:
- [ ] Parameter descriptions with types and required/optional status
- [ ] A curl example request
- [ ] An example JSON response
- [ ] An error code table

Tips & Best Practices

1. Include a real example request and response, not just schema — Developers learn faster from concrete examples than from abstract type descriptions. Always ask Claude to include a real-looking example alongside the schema. “Use realistic-looking example data, not placeholder values like string or 1234.”

2. Ask Claude to flag ambiguities in the code — When generating docs from code, add: “If there’s anything in the implementation that’s unclear or that you had to infer rather than read directly, flag it so I can verify.” This catches cases where Claude had to guess at intended behavior.

3. Document error cases thoroughly — Most API docs over-document happy paths and under-document errors. Explicitly ask: “For each error case, describe: the HTTP status code, the error response body structure, what triggered the error, and what the caller should do about it.”

4. Use Claude to write the authentication section once, then reuse it — Authentication is the same across all endpoints. Ask Claude to write a thorough authentication section once, then tell it to reference that section rather than repeat it for every endpoint.

5. Generate Postman collections alongside docs — After generating OpenAPI YAML, ask: “Also generate a Postman collection JSON for this endpoint with the same example request.” This gives developers something to import and test immediately, not just read.

Try It Yourself

Find an API endpoint in your codebase that has no documentation or sparse documentation. Paste the route handler into Claude with this prompt:

“Generate a complete Markdown API reference for this endpoint. Include: a one-sentence description, a parameter table (name, type, required, description), a curl example with realistic-looking data, a success response example, and a table of error codes with explanations.”

Add the result to your project’s README or docs folder and see how much faster new team members can understand and use that endpoint.