How to Generate API Reference Pages from OpenAPI in Mintlify
You generate a Mintlify API reference by adding an openapi field to a page in docs.json that points at your spec file. Mintlify builds endpoint pages, request builders, and a live playground — no hand-written endpoint docs.
Hand-written API docs rot within one release. A generated reference only rots when the spec does, and your code owns the spec.
How do you wire the spec in?
Write the spec to your repo as openapi.json or yaml, then reference it from a page:
{
"group": "API reference",
"pages": [
{ "page": "API reference", "openapi": "openapi.json" }
]
}
One page entry produces a whole section, split by your spec’s tags. If your endpoints share one tag called “default”, you get one giant scrolling page. Tags are the navigation.
Generate the file from your framework rather than writing it by hand: FastAPI gives you a free /openapi.json, Express needs swagger-jsdoc, and NestJS has @nestjs/swagger with a CLI plugin.
Why does the playground fail to send requests?
Almost always CORS. The playground is a browser form; it calls your API directly from the docs domain. If your server’s Access-Control-Allow-Origin does not include docs.yourdomain.com, every request fails silently in the network tab.
The fix is one line on your API, or use a proxy setting in the spec’s playground config to route through Mintlify’s proxy. The proxy is simpler and keeps CORS closed, but it means your auth tokens pass through a third party — mention that in your own security review.
Second most common failure: a server URL of http://localhost:8000 left in the spec’s servers array. The playground then posts to the reader’s own machine.
How do authentication schemes work?
Define them once in components.securitySchemes, then reference them per operation. Mintlify renders the right input — an API key field, a bearer token box, or an OAuth button — based on type.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
For real production docs, do not put a live key in the example values. Ship a sandbox key that expires and rate-limits hard. People click the playground button on their first visit, and a leaked key from your docs is a bad first impression.
What makes the AI answers accurate?
Two things: descriptive summary fields on every operation, and description on the parameters. The AI search indexes spec text, so summary: "Create invoice" gives it far more than summary: "POST /v2/invoices".
Add a short description per endpoint with the failure modes — “Returns 409 if the invoice already exists for that period.” That single sentence saves a dozen support threads, and it feeds the assistant.
Versioning a spec without breaking links
Keep one file per major version: openapi.v1.json, openapi.v2.json, each behind its own page. Do not overwrite a published spec — every anchor link and every customer integration doc points at those URLs.
For a staged rollout, point the docs page at the new file behind an unlisted path, review it, then move the page entry. Redirects go in docs.json under redirects, and they are checked at build time, so a typo fails the build instead of shipping.
Honest limitations
- Complex nested
oneOf/anyOfschemas render poorly; expect to split them into referenced components. - Specs over roughly 5 MB slow down the docs build noticeably.
- There is no automatic changelog. If your API ships weekly, you still write the release notes by hand — or generate them from git tags.
Key Takeaways
- Add
{ "page": ..., "openapi": "openapi.json" }todocs.jsonto generate a whole reference section. - Organise nav with OpenAPI
tags; one tag means one very long page. - Playground failures are usually CORS on your API or a localhost entry in
servers. - Put real descriptions on every operation — the AI assistant indexes that text.
- Version specs as separate files; never overwrite a published one.
