Code
Document an API
Browsable reference with real request and response examples.
Fill it in
Point at the code, or describe the endpoints.
Emit a spec alongside the pages.
Every failure a caller has to handle.
Your prompt
Document this API. [the service] Write the examples from real calls. A reference whose examples were composed by hand always has one wrong field name, and the reader who hits it stops trusting the entire document. Every endpoint: what it is for, the parameters with types and whether they are required, an example request, an example response, and the status codes. Document the ERRORS properly. What a caller needs is the list of ways it can fail and what to do about each; "400 Bad Request" is not documentation. Emit an OpenAPI spec alongside the pages, generated from the same source so the two cannot drift. Auth first, because nothing else works until that does.
Use Document an APIOpens with everything above already filled in.
Why this works
A reference whose examples were composed by hand always has one wrong field name, and the reader who hits it stops trusting the whole document. This writes examples from real calls and documents the errors properly, since what a caller needs is the list of ways it fails and what to do about each.
Questions
- Do I get an OpenAPI spec?
- Yes, generated from the same source as the pages so the two cannot drift.