The prompt
Score 10 of 10, Excellent
Use it when An internal or public API has endpoints nobody documented, and you want reference docs written from what the code actually does.
- {{audience}}
- {{reader_goal}}
- {{stack}}
- {{base_and_auth}}
- {{code}}
- {{existing_notes}}
Full prompt and why it works
Prompt
Write reference documentation for the API code below, for {{audience}}. They will use it to {{reader_goal}}, so the docs should be accurate to what the code does today, not to what its names suggest. Language and framework: {{stack}} Base URL and authentication, as far as I know: {{base_and_auth}} Code (route handlers, request and response types, validation and error handling): """ {{code}} """ Existing docs or notes, if any: """ {{existing_notes}} """ For each endpoint, in the order it appears in the code, write: - A heading with the method and path, for example "GET /invoices/{id}", and one sentence on what it does. - Authentication and permissions required, as the code enforces them. - Parameters: a table with the columns Name, In (path, query, header or body), Type, Required, Description, including defaults and the validation rules found in the code. - Responses: each status code the code can return, when it happens, and an example body built from the response types, with example values marked as examples. - Limits and side effects: pagination, size limits, rate limits, or side effects such as an email being sent, only where the code shows them. Format the result as Markdown. Keep each endpoint's prose under 150 words, not counting tables and example bodies. Document only behavior you can see in the code. Do not invent endpoints, fields, status codes or limits, and do not repeat comments that the code contradicts. Where behavior depends on code that is not included, such as a middleware or a shared validator, say so in that endpoint's section and assume nothing about it. At the end, list "Questions for the API owners": anything unclear, and every place where the code and the existing notes disagree.
Variables
- {{audience}}
- Who reads the docs, for example "developers on other internal teams" or "engineers at customer companies".
- {{reader_goal}}
- What they need to do with the docs, for example "build an integration without asking us questions".
- {{stack}}
- For example "Python with FastAPI" or "TypeScript with Express".
- {{base_and_auth}}
- The base URL and how callers authenticate, for example "a bearer token in the Authorization header". Write "unknown" if you are not sure.
- {{code}}
- The route handlers and the types, schemas and validation they use.
- {{existing_notes}}
- Any existing docs, README sections or comments about the API. Write "none" if there are none.
Why it works
- What to avoid. It documents only behavior visible in the code and ignores comments the code contradicts, so the reference matches what callers will actually get.
- Format. Every endpoint gets the same parts, a parameter table and status codes with example bodies, which is the layout developers scan for.
- If unsure. Behavior hidden in code that was not pasted, and conflicts with older docs, become questions for the API owners instead of assumptions.