The prompts that produce clear API documentation give the AI model the real source material, such as the OpenAPI spec, the handler code or a captured request and response, and ask for a fixed structure, instead of describing the endpoint in a sentence and hoping. They also tell the model to mark anything the source does not state rather than fill it in. Below are six copy-ready prompts for docstrings, endpoint reference pages, a getting-started guide, docs from Postman collections, error tables and rate-limit pages, plus a review prompt to catch invented details.
Featured image: “Code on computer monitor” by Markus Spiske, released under CC0.
API documentation is the material developers read to call your API correctly: what each endpoint does, which parameters it takes, what it returns, how authentication works and what errors mean. Its quality is judged by one test: can a developer make a successful first call, and handle the failures, without asking you?
Why AI-written API docs go wrong
AI-written API docs fail in a predictable way: they are fluent, well formatted and partly invented. A model asked to “document the orders endpoint” will produce plausible parameter names, typical status codes and a sensible-looking example, drawn from thousands of other APIs rather than yours. A developer who trusts that page sends a request that cannot work.
The fix is to change what the model is doing. Instead of writing documentation from general knowledge, it should be transforming a source of truth into readable prose. Every prompt below follows three rules:
- Provide the source. The OpenAPI document, the route handler and validation code, or real request/response pairs.
- Fix the structure. The same headings in the same order for every endpoint, so readers know where to look.
- Forbid invention. Anything not in the source becomes a visible
TODOfor a human, not a guess.
That third rule is the documentation version of a general technique covered in our guide to reducing AI hallucinations with better prompts.
Which prompt to use for which source
The right prompt depends on what you have and what kind of page you need. Documentation frameworks such as Diátaxis separate tutorials, how-to guides, reference and explanation because each serves a different reader need; the prompts map to those types.
| You have | You need | Prompt | Doc type |
|---|---|---|---|
| Function or handler code | Docstrings that feed generated reference | 1 | Reference |
| OpenAPI document | Endpoint reference page | 2 | Reference |
| Auth flow and one core endpoint | First successful call in minutes | 3 | Tutorial |
| Postman collection or curl commands | Reference or OpenAPI draft | 4 | Reference |
| Error handling code | Error table with fixes | 5 | Reference / how-to |
| Rate limiter configuration | Rate-limit page with retry guidance | 6 | How-to |
Prompt 1: Docstrings for handlers and SDK methods
Docstrings are the cheapest documentation to keep current because they live next to the code and many frameworks generate reference pages from them. The prompt asks the model to document what the code actually does, including behavior a reader would not guess.
Write a docstring for the function below in Google style (Python).
<code>
[paste the handler or SDK method, plus any validation schema it uses]
</code>
Include:
- One-line summary starting with a verb ("Create", "List", "Cancel").
- Args: name, type, whether required, default, and constraints that the code enforces.
- Returns: type and shape.
- Raises: every exception the code can raise, and the condition that triggers it.
- Side effects: writes, emails, webhooks, cache invalidation.
Rules:
- Describe only what the code does. If a constraint is enforced elsewhere and not
visible here, write "TODO: confirm" instead of guessing.
- Do not describe implementation details callers do not need.Why the side-effects line exists: “this also sends a confirmation email” is the kind of fact callers need and code readers miss. For inline comments beyond docstrings, see our prompts for code comments and inline documentation.
Prompt 2: Endpoint reference page from an OpenAPI spec
The OpenAPI Specification is the standard, language-agnostic format for describing HTTP APIs, and the current release on the official specification page is version 3.2.1. It already contains paths, parameters, schemas and responses, so it is the best possible input for a reference page. (Swagger is the name of the original tooling around the format; the specification itself is called OpenAPI.)
You are writing reference documentation for one endpoint.
Source of truth: the OpenAPI excerpt below. Use nothing else.
<openapi>
[paste the path item, plus every schema it references via $ref]
</openapi>
Produce Markdown with exactly these sections, in this order:
## {METHOD} {path}
One sentence: what it does and when to use it.
### Authentication
### Path and query parameters (table: name | type | required | description | example)
### Request body (table, then one complete JSON example)
### Responses (one subsection per status code in the spec, with example)
### Example request (curl, using placeholder token $API_TOKEN)
### Notes (idempotency, pagination, ordering - only if in the spec)
Rules:
- If the spec lacks a description, example, or constraint, write "TODO: not in spec".
- Examples must validate against the schemas. Use obviously fake values
(ord_123, jane@example.com).
- Do not add status codes that are not in the spec.The TODO: not in spec markers are a feature: they show you where the spec itself is incomplete. Fix those gaps in the OpenAPI document, not only in the prose, so generated SDKs and other tools benefit too. The spec’s description fields support CommonMark, so improved wording can live in the spec itself.
Before and after: one parameter
A vague prompt typically produces a row like “limit: The number of results to return.” With the spec as source, the same row becomes specific, because the schema says integer, minimum: 1, maximum: 100, default: 20:
| limit | integer | no | Maximum orders per page. 1-100, default 20. Values above 100 return 400 invalid_parameter. | 50 |The error behavior in that row comes from the response section of the spec. If the spec does not say what happens above 100, the prompt’s rules make the model write TODO instead.
Prompt 3: A getting-started guide that ends in a working call
A getting-started guide is a tutorial: its only job is to take a new developer from zero to one successful request. It should not list every option. The prompt keeps the model on that single path.
Write a getting-started tutorial for our API.
Reader: a backend developer who has never used our API, using curl or Python.
Goal: they create an API key and make one successful POST /v1/orders call.
Source material:
<auth>[how keys are created and sent: header name, format, sandbox vs live]</auth>
<endpoint>[OpenAPI excerpt for POST /v1/orders]</endpoint>
<base_urls>[sandbox and production base URLs]</base_urls>
Structure:
1. Prerequisites (one short list)
2. Get a sandbox API key
3. Make your first request (curl, then Python with requests)
4. Read the response (point out the 2-3 fields they will use next)
5. If it fails (the 3 most likely errors from the spec and how to fix each)
6. Next steps (links only, as placeholders)
Rules: numbered steps, one action per step, every command copy-pasteable,
sandbox only, no option the reader does not need for this one call.Section 5 is what separates a useful tutorial from a demo. Most first calls fail on authentication header format or a missing required field, and naming those failures saves a support ticket. Test the finished guide by following it exactly in a clean environment; if any step needs knowledge the page does not give, the guide is not done. Your project README should link here; our prompts for README files and project documentation cover that page.
Prompt 4: Turn a Postman collection or curl commands into docs
Many APIs have no spec but do have a Postman collection or a folder of curl commands that the team actually uses. Those captured requests are real evidence of how the API behaves, and the model can turn them into a reference draft or a starter OpenAPI document.
Below are real requests and responses captured from our API (secrets replaced).
<captures>
[paste exported collection JSON, or curl commands with their full responses]
</captures>
1. Draft an OpenAPI 3.1 document covering every endpoint in the captures.
2. Infer types and required fields only from what the captures show. For each
inference, add an x-inferred: true extension so a human can confirm it.
3. List every question the captures cannot answer (for example: is this field
always present? what are the allowed status values?).
4. Do not invent endpoints, parameters, or error responses that are not captured.The x-inferred marker uses OpenAPI’s extension mechanism (fields starting with x-) to flag every guess for review. Before pasting anything, strip tokens, cookies, API keys and real customer data from the export. The question list from step 3 is the agenda for a short conversation with the developers who own the API.
Prompt 5: An error reference table developers can act on
An error reference turns status codes and error codes into instructions: what happened, why, and what to do. If your API does not already have a consistent error format, RFC 9457, Problem Details for HTTP APIs, defines a standard JSON shape with the media type application/problem+json and members such as type, title, status, detail and instance. It replaced RFC 7807 in 2023.
Build an error reference for our API from the code below.
<code>
[paste the error classes, the exception-to-response mapping, and validation code]
</code>
Output a Markdown table with columns:
HTTP status | error code | when it happens | how to fix it (client side) | retry?
Rules:
- One row per distinct error code the code can return. No generic rows.
- "How to fix it" must be an action the API caller can take, not "contact support",
unless the error truly requires it.
- "Retry?" is one of: no / yes, after fixing the request / yes, with backoff.
- After the table, show one full example error response body exactly as the code
produces it.
- If an error message leaks internal details (stack traces, SQL, hostnames),
list it separately under "Messages to fix".The “Messages to fix” section often finds real problems: error messages that reveal internals are a documentation issue and a security issue. Our prompts for error messages and log output help rewrite them.
Prompt 6: Document rate limits without assuming a standard
Rate-limit documentation must describe the headers your API actually sends, because there is no finalized standard yet. The IETF HTTPAPI working group’s RateLimit header fields draft defines RateLimit-Policy and RateLimit fields, but it is still an Internet-Draft (version 11, May 2026), not an RFC. Many APIs use other names, such as X-RateLimit-Remaining, and a model left to guess may describe the draft’s headers for an API that does not send them.
Write a "Rate limits" page for our API.
Source:
<config>[rate limiter configuration: limits per key/plan/endpoint, window type]</config>
<sample_429>[a real 429 response, including all headers]</sample_429>
Sections:
1. Limits (table by plan and endpoint group, from the config only)
2. Headers we return (exact header names from the sample, with meaning)
3. What happens when you exceed a limit (status, body, Retry-After if present)
4. How to retry (exponential backoff with jitter; respect Retry-After when sent)
5. Example retry loop in Python
Rules: use only header names that appear in the sample response.
Do not mention headers we do not send.The review prompt: check the draft against the source
Every generated page should get a verification pass in a fresh session that compares the documentation against the source and lists differences. Asking the model to find mismatches is more effective than asking whether the page is correct.
Compare the documentation to the source of truth. Find every mismatch.
<source>[OpenAPI excerpt or code]</source>
<docs>[generated page]</docs>
List:
1. Parameters, fields, headers, or status codes in the docs but not in the source.
2. Items in the source missing from the docs.
3. Types, required flags, defaults, or limits that differ.
4. Examples that would fail validation against the source schemas.
5. Statements the source does not support (any claim about behavior).
Quote the exact line from the docs for each finding.Then do the one check no model can do for you: run every example request against a sandbox. A page whose examples execute successfully is far more trustworthy than one that only reads well.
Keeping AI-generated docs from drifting
Documentation drifts when the API changes and the prose does not. A few habits keep generated docs in sync:
- Make the spec the source of truth. Improve descriptions in the OpenAPI file and regenerate pages from it, instead of editing generated Markdown by hand.
- Regenerate on change. When a pull request changes an endpoint’s schema, rerun Prompt 2 for that endpoint and include the doc diff in the same pull request.
- Test examples in CI. Validate example payloads against the schemas automatically so broken examples fail the build.
- Keep a style block. Save your tone, terminology and formatting rules in one reusable instruction block or system prompt so every page reads the same; see our guide on how to write a system prompt.
- Never paste secrets. Replace keys, tokens, internal hostnames and customer data with placeholders before any source goes into a prompt.
