Set up an API reference
Add an OpenAPI spec to your repo and generate API pages from it.
Generate API pages from an OpenAPI spec in your repo. For what the pages contain and the current limits, see API reference overview.
Prerequisites
- A docs site connected to a GitHub repo. See Connect GitHub.
- An OpenAPI spec in JSON, committed to your docs directory. YAML isn't supported yet — convert it to JSON first.
Add an API reference
Add the spec to your repo
Commit your OpenAPI file to the docs directory, next to docs.json. Any path works — for example openapi.json at the root, or api/openapi.json in a subfolder.
Point a group at the spec
Add an openapi field to a navigation group in docs.json — a top-level group, or a group inside a tab. The value is the spec's path, relative to your docs directory, with the .json extension.
{
"navigation": [
{
"group": "API reference",
"openapi": "openapi.json"
}
]
}Push to deploy
Commit and push. On the next deploy, Bloques reads the spec and adds one page per operation under the group.
Control titles and URLs
The spec sets how each page reads in the sidebar and the address bar:
- Sidebar label and page heading — the operation's
summary, falling back to itsoperationId, thenMETHOD /path. Add asummaryto each operation for readable labels. - URL — a lower-cased form of the operation's
operationId, falling back tomethod-path. Set anoperationIdfor stable URLs that don't change when you edit a path.
An operation with summary: "List all pets" and operationId: "listPets" in a group named "API reference" renders as List all pets in the sidebar, served at /api-reference/listpets.
Add written pages alongside
A group can list its own pages next to openapi. Written pages come first, then the generated operations — room for an overview or authentication page above the endpoints.
{
"group": "API reference",
"pages": ["api/overview", "api/authentication"],
"openapi": "openapi.json"
}Put it in its own tab
To separate the API reference from your guides, set openapi on a group inside a tab. The tab becomes its own entry in the top navigation, with the operations in its own sidebar.
{
"tab": "API reference",
"groups": [{ "group": "Endpoints", "openapi": "openapi.json" }]
}The operation URLs sit under the tab — for example /api-reference/endpoints/listposts.
Update the reference
Edit the spec, push, and the pages regenerate on the next deploy. No generated files to commit or keep in sync.
Troubleshooting
| Problem | Cause and fix |
|---|---|
| No API pages appeared | The path is wrong, the file is missing, or it isn't valid JSON. A bad spec is skipped — it doesn't fail the deploy — so the rest of the site still builds. Check the path and validate the JSON. |
openapi is set but nothing generated | openapi is read on a top-level group or a group directly inside a tab — not on a group nested inside another group. Move it up a level. |
| Pages render but playground requests fail | The request runs from the browser, so your API must allow cross-origin requests (CORS) from your docs domain. |
| A YAML spec produces no pages | Only JSON is supported. Convert the spec to JSON. |