If you have an OpenAPI 3.x spec, you don't need to write API reference pages by hand. Upload the spec to Dokly and it generates one page per endpoint, organized by tag, with the playground wired up automatically.
Pro plan or higherSetup#
Open Project Settings → API → OpenAPI
Screenshot needed
screenshot of the OpenAPI settings panel showing upload area
Upload your spec
Drag in your openapi.yaml or openapi.json. Dokly accepts OpenAPI 3.0 and 3.1.
For specs hosted at a URL (e.g., a public spec on GitHub), paste the URL — Dokly fetches and re-validates.
Pick a parent page
Generated pages need to slot into your page tree somewhere. Pick a parent (commonly an "API Reference" page you've already created).
Pick a base URL
OpenAPI specs can list multiple servers (production, staging). Pick which one the playground sends requests to. You can also let readers switch.
Generate
Dokly creates one page per path × method combination. A spec with 30 endpoints across 6 tags becomes 30 pages organized into 6 groups in your sidebar.
Generation usually takes 5–15 seconds. The pages appear in the tree as they're created.
What gets generated#
For each endpoint:
| Section | Source |
|---|---|
| Page title | summary |
| Description (top of page) | description |
| Method + URL badge | OpenAPI path and method |
| Parameters table | parameters (path, query, header) |
| Request body schema | requestBody.content |
| Authentication | security (or project default) |
| Response examples | responses[code].examples or examples |
| Code samples | Auto-generated from spec (curl, JS, Python, Go, Ruby) |
| Playground | Configured from all of the above |
The page is editable. Anything you change is preserved on next sync — see below.
Re-syncing after spec changes#
When your API changes, re-upload the spec. Dokly does a 3-way merge:
- New endpoints — added as new pages.
- Removed endpoints — pages soft-deleted (recoverable for 30 days).
- Changed endpoints — auto-generated sections (parameters, schema, codes) are updated; your manual edits (added prose, examples, callouts) are preserved.
You'll see a diff before each sync so you can review changes.
Custom prose around generated content#
The generated pages have an "Editable narrative" section between the header and the playground. Add anything: when to use this endpoint, common gotchas, links to related guides. This content survives re-syncs.
## When to use this endpoint
Use `/users` for CRUD. For bulk operations (>100 users), use the
batch endpoint at `/users/batch` — it's optimized for throughput.
## Common errors
- `403` usually means the user is on a Free plan. Check `/users/me/plan` first.
- `429` from this endpoint is per-account, not per-token. Wait the
`Retry-After` window before retrying.Multi-language code samples#
Code samples are auto-generated for: curl, JavaScript (fetch), Python (requests), Go, Ruby.
The samples include real placeholders for your specific request shape — they're not generic. A POST endpoint with a body shows the body filled in; a GET with query params shows the params in the URL.
You can hide languages your audience doesn't use in Project Settings → API → Code Samples.
Limitations#
- OpenAPI 2.0 (Swagger) — not supported. Convert to 3.0 first using a tool like swagger-converter.
- AsyncAPI — not supported.
- GraphQL — separate import flow, on the roadmap.
- gRPC / proto — not supported.
Common issues#
My spec validates locally but Dokly rejects it
Dokly uses strict OpenAPI 3.x parsing. Common gotchas: missing required fields (info.version, info.title), $refs pointing to external files (Dokly resolves only inline $refs today), or nullable: true in places it's not allowed in 3.1.
Run npx @redocly/cli lint openapi.yaml for a strict validation that matches Dokly's behavior.
The generated pages are in the wrong order
Endpoint order within a tag is the order they appear in the spec. Reorder by editing the spec, or drag the pages in the tree after generation — manual order overrides spec order on re-sync.
Can I generate from multiple specs?
Yes — upload multiple specs into different parent pages. Common pattern: separate specs for v1 and v2 of an API, each generating into its own section.