API Documentation and Reference Template
Seven documents and three sheets, including the error reference keyed on problem type and a coverage check that says which of your examples actually validate.
Free download · No account needed
Your generator already produced a reference page. Every endpoint is on it, every parameter has a type, and the build is green. The gap is what the specification never said, and it is permitted in writing: OpenAPI requires the Responses Object to carry one response code, and says that where only one is provided it should be the successful one. An operation returning five distinct failures while declaring a single 201 is a conforming document, so no linter has grounds to complain and no generator can invent the rest.
The second gap is that an example is never checked against the schema printed beside it. In JSON Schema 2020-12 the examples keyword sits in the vocabulary for basic meta-data annotations, and validity against the associated schema is recommended rather than required. So a request example sending a renamed field is a valid document, nothing errors, and it ships. An example wrong for eleven months is the version of your API that your integrators actually built against.
So this pack ships two registers a generated page cannot produce. One counts declared failures separately from declared responses and never credits a bare default. The other carries present, validates and runs as three columns, plus which example wins when two collide. Alongside them, the error reference is keyed on problem type, because one status code is not one error. For code you did not write, start from the inherited codebase documentation instead.
What's in the pack
Endpoint Register
One row per operation, counting declared responses and declared failures separately, never crediting a bare default, with four states including the operations missing from the spec entirely.
Example Coverage Check
One row per example, carrying present, validates and runs as three columns, the first schema failure on each, and which example wins when two collide.
Problem Type Register
One row per type URI with its extension members, the cause, whether the URI resolves, and what the integrator should actually do about it.
Error Reference
The document each locator type URI resolves to, with two failures on one status code written up separately because the correct response to each is the opposite.
Reading a Specification
Every claim above quoted from the primary source, so the register survives the first person who asks why their linter never mentioned any of this.
Getting Started and Authentication Guide
A three-call quickstart with the real failure at each step, plus scopes, idempotency, key rotation and webhook signature verification.
Changelog
Where a deprecation date, its replacement and its migration live, since the specification's deprecated field is a boolean with nowhere to put any of the three.
How to use it
- 1
Open in River, or take it blank
Send the pack your OpenAPI or Swagger document inside River, or download the seven documents and three sheets and work through them without an account.
- 2
Count before you judge
Declared responses and declared failures land as separate columns, and a bare default is named rather than counted as error documentation.
- 3
Check every example
Each one is validated against the schema beside it, then sent, because a passing schema check and a working request are different questions.
- 4
Key the errors on type
Problem types come from what production returns rather than what the document declares, and each locator URI gets the page the standard says it owes.
Frequently asked questions
Is this template free?
Yes, and the download needs no account and no card. Edit with AI is the optional half: it reads the specification you send, fills the endpoint register, and checks every example against the schema printed beside it. Every other pack is in the template library.
What format are the downloaded files?
Seven documents as Word files and three sheets as CSVs, in one zip. The sheets open in Excel, Numbers or Google Sheets with the columns already ordered, and the documents open in Word or Pages. Nothing needs converting to be readable.
We already generate docs from OpenAPI. What does this add?
The two things your generator has no input for. It cannot show a failure your document never declared, and it cannot tell you that a published example contradicts the schema above it. Both are permitted by specification, so nothing in your pipeline reports either one.
Why not just list our error codes in a table?
Because one status code is not one error. RFC 9457 requires consumers to use the type URI as a problem type's primary identifier and makes the status member advisory. Two failures on 409 where retrying fixes one and causes the other cannot share a row without producing a retry loop.
How does it find endpoints that are not in our spec?
By comparing the document against what actually serves traffic: your route definitions, your gateway config, and the paths in your access logs. No generator can do this, because a tool cannot report what is absent from its own input, so an endpoint that shipped behind a flag stays invisible.
Our examples look fine. Are they?
Nothing has checked. Both specifications say an example should match its schema and neither says must, so a mismatch is a conforming document. The coverage sheet reports the first failure on each, then sends it, since an example can validate cleanly and still return a 409.
What else should we document alongside this?
The data layer and the release trail. The database schema documentation covers the tables behind these endpoints, release notes from commits turns a merge history into what changed for a user, and the data pipeline pack covers the jobs feeding them. Once an operation here is on its way out, the API deprecation policy pack works out who still calls it.
Find out what your specification never said
Take the Word documents and CSV sheets blank, or open this exact pack in River and let it read the specification you already publish.
Edit with AI