API reference overview
Generate interactive API docs from an OpenAPI spec, in sync on every push.
Bloques turns an OpenAPI spec into a browsable API reference: one page per endpoint, with parameters, schemas, example requests, and a playground for sending live calls. Point a navigation group at a spec file and the pages appear on your next deploy. This page covers how generation works and where its limits are. For the setup steps, see Set up an API reference.
How it works
The spec drives everything, on the same push-to-deploy flow as the rest of your site:
- An OpenAPI spec (JSON) lives in your repo, alongside your MDX pages.
- A navigation group in
docs.jsonpoints at the spec through itsopenapifield. - On each deploy, Bloques reads the spec and generates one page per operation under that group.
The spec stays the single source of truth — no generated files land in your repo to commit or keep in sync. Edit the spec, push, and the pages update. Each page renders from the spec when a reader opens it, so the reference always matches what you shipped.
What each page includes
Every operation in the spec becomes a page with:
- Endpoint summary — method, path, and the operation's description.
- Parameters — path, query, header, and body parameters with their types and constraints.
- Schemas — request and response bodies with example values, expandable by field.
- Code samples — example requests in multiple languages, ready to copy.
- Playground — an interactive panel for sending a real request and reading the response.
Mix generated pages with hand-written ones in the same group — an overview or authentication guide above the endpoints, for example.
Each generated page is also available as markdown for AI tools, listed in /llms.txt alongside the rest of your site. See LLM endpoints.
What isn't supported yet
| Not supported | Detail and workaround |
|---|---|
| YAML specs | Only JSON is read. Convert the spec to JSON first. |
| Multi-file specs | The spec must be self-contained. A $ref pointing to a separate file isn't resolved — bundle everything into one document. |
openapi on a nested group | The field is read on a top-level group or a group directly inside a tab — not on a group nested inside another group. |
| Grouping by tag | Operations list in spec order, not split into sections by their OpenAPI tags. |
| Top-level webhooks | Only operations under paths generate pages. webhooks entries don't. |
| Hiding or reordering individual operations | Every operation generates a page, in spec order. Control the set and order by editing the spec. |