Recipe: Sync Your OpenAPI Spec
Keep generated API reference pages in sync with your OpenAPI spec on every release.
Import an OpenAPI 3.x spec and Syntext generates endpoint pages — request/response schemas, code samples, and an interactive try-it playground. This recipe keeps the spec in sync automatically.
Recommended: Keep Specs in Your Docs Repo
Commit your specs next to your docs and list them in syntext.json:
Every build re-reads the specs and regenerates the endpoint pages, so your API reference is synced on every deploy — no extra pipeline step. A single spec can be passed as a plain string ("openapi": "./openapi.json"), and remote specs via url entries are fetched fresh at build time.
With a prefix, endpoint slugs are derived from the HTTP method and path ({prefix}/get-v1-users-user-id), never from operationId, so generated URLs survive operation renames. Without one — the plain-string form, and specs added in the dashboard — they are api-reference/{tag}/{operationId} (method and path when there is no operationId); see Page URLs. If you create an MDX file at the same path as a generated page, your file wins — hand-tune any page without losing the rest of the generation. See openapi in syntext.json for all accepted forms.
Alternative: One-Time Import via API
Point Syntext at a spec URL or upload the document. These endpoints take a
project API key with the build
scope (or full), or a session token (from stx login or the dashboard). A
key works only for its own project; a read key gets 403.
source is url (with url) or inline (with the document as a string in
content). Optional specId and label name the spec when a project has
several.
Generated endpoint pages appear under your API reference tab after the next build.
What Gets Rendered
Each generated endpoint page includes the method badge, path, parameters, request/response schemas, code samples, and a try-it playground. The generator understands the following spec features:
Security schemes
The playground's Authorization field follows each operation's security requirement and your spec's securitySchemes — never a guess:
http / bearer — sends Authorization: Bearer <token>; with bearerFormat: JWT, samples write <jwt>http / basic — the reader types username:password, sent as Authorization: Basic and its base64apiKey — the field is labeled with the scheme's own name (e.g. Api-Key) and the key is sent as that header, as a query parameter for in: query, or (in Copy as code only; a docs page can't set it) as a cookie for in: cookieoauth2 and openIdConnect — a token the reader already has, sent as a Bearer token; the console says soA scheme's description appears under the field. When an operation accepts several schemes (an API key or a JWT), Try it shows a chooser and the samples use the first. An operation with security: [] gets no credential field, and an API whose spec declares no security at all shows none either, unless syntext.json declares auth. Code samples and Try-it requests all use the resolved scheme.
You can also declare the auth scheme directly in syntext.json — useful when the spec's securitySchemes are missing or wrong. A top-level auth key applies to every spec (and to hand-authored REST pages); an auth key on an openapi entry overrides it for that spec only:
auth takes a scheme such as { "type": "bearer", "label": "Session token", "bearerFormat": "JWT" }, a list of alternatives, or the v1 form (name, plus optional label, in and prefix); see Declaring auth. Precedence: page auth frontmatter > per-entry auth > top-level auth > the spec's security and securitySchemes. An operation with security: [] stays public.
Header parameters
Parameters with in: header render in their own Headers section on the page and in the playground, where readers can fill them in — values are included in code snippets and sent with Try-it requests. The auth header itself is excluded to avoid duplicating the Authorization field.
Headers the spec doesn't declare can be added from syntext.json — a top-level headers array applies to every spec, and a headers array on an openapi entry overrides it for that spec:
Spec-declared parameters win on name collisions, and a config header matching the auth header name is dropped.
Markdown descriptions
Operation description fields render as full Markdown — headings, bullet lists, and multiple paragraphs all work. The first paragraph (flattened to one line) becomes the page's meta description.
Nested schemas, enums, and variants
Schema properties render recursively up to 4 levels deep. Nested object properties appear in an expandable "properties" section. Two schema shapes get special treatment:
enum — allowed values render as a "Possible values" list under the field descriptiononeOf / anyOf — each variant renders in its own expandable block, labeled by the variant schema's title (falling back to its type, then "Variant 1", "Variant 2", …)Multiple named examples
Every entry in a request or response content.examples map renders as its own code block, titled with the example's name:
A single example (singular) renders as one block titled "Request" or "Response".
Request code samples
The right-hand request panel auto-generates snippets in seven languages — cURL, Python, JavaScript, PHP, Go, Java, and Ruby — from the operation's method, path, and server URL. If the spec provides a request body example, the snippets use that real payload instead of placeholder values.
Multiple base URLs (production + sandbox)
When more than one base URL is declared, the API playground shows a base-URL selector, and code snippets plus Try-it requests follow whichever server the reader picks. The simplest way is a top-level baseUrls key in syntext.json — it applies to every spec and to hand-authored REST pages:
Plain strings work too: "baseUrls": ["https://api.example.com", "https://sandbox.example.com"].
Alternatively, declare servers in the spec itself:
Or, if one spec needs different hosts than the rest of the site, set servers on that openapi entry:
Precedence: per-entry servers > top-level baseUrls > the spec's own servers list. The first base URL is the default; when only one is declared, no selector renders.
Sandbox servers for assistant runs
With Run API requests from answers on, the agent mode assistant can prepare a request for a reader to run with their own key. Each production build saves your spec's endpoints and servers as the project's endpoint catalog, and runs go to a server from it:
x-syntext-sandbox: true, if one isMark the sandbox with the same key wherever you declare servers. In the spec:
In syntext.json baseUrls, or an openapi entry's servers (they replace the spec's servers, so mark it there):
Only true counts. A description or URL that says "sandbox", "test" or "staging" is never taken as a marker, and plain-string baseUrls can't carry one. The run card always shows the host, and labels the request Sandbox or Live API. The catalog is updated by production builds only; a production build with no spec removes it, and one whose spec failed to generate keeps the previous catalog.
Examples on doc engine v2
A v2 endpoint page always shows a Request example and a Response
example with one tab per status. The request comes in cURL, JavaScript,
Python, Go, Ruby, PHP, Java and C# by default; choose your own list and order
with api.requestLanguages in
syntext.json (curl, javascript, typescript, node, python, python-httpx, go, ruby, php, java, csharp, rust, swift, kotlin and http). With more than four languages the panel shows the
first three as tabs and the rest in a language menu; on phones the menu
replaces the tabs. A reader's choice is remembered across pages and also
switches <CodeGroup> tabs with the same label.
Every language sends the same request: your first base URL (or the path
alone when none is declared, never a made-up host), path parameters from
their example or default (else {name}), query parameters that are
required or have an example, and a JSON body with Content-Type only when
the operation has a request body. The credential, only when the operation declares one, is a
placeholder for its scheme (Bearer <token>, <jwt> for bearerFormat: JWT,
or <api-key> for a key), never a made-up key. Values come from
your spec: a media-type example / examples first; otherwise the response
example is built from the schema — each field's example, else its
default, else its first enum value, else a value of its type. Request
samples use the same field and parameter example values ("branch": "main"
rather than "branch": "branch"). A response with no schema (a 204) has no
tab. v1 pages are unchanged.
A long line scrolls sideways inside its code block rather than being cut off: the edge that hides code fades out, and a thin scrollbar shows on hover or keyboard focus. A block that overflows can be focused and scrolled with the arrow keys.
Hand-written endpoint pages get the same languages beside the examples you write: your tabs stay first, exactly as written, and every configured language they leave out is generated from your own cURL — see REST frontmatter. OpenAPI pages have no authored samples, so every language there comes from the spec.
API overview on doc engine v2
On a v2 site, each spec gets a generated API overview page, titled with the
spec's info.title. It is filled from your spec:
info.description, then a table of your tags.servers, with a copy button.auth block in syntext.json replaces the schemes.X-RateLimit-*, RateLimit-*, X-Rate-Limit-* and Retry-After, followed
through $ref — as a Header / Meaning table, each with the first
line of its first description.x-speakeasy-pagination
(its inputs) or x-fern-pagination (its $request.* values) on the first
operation that has one, with their type, location, default and description.
Only names the operation declares as query or header parameters count.api in syntext.json
wins section by section: a rateLimits or pagination there replaces what
the spec gives for that section, and it can add plan tiers and a sample page
of results, which a spec can't. SDKs cards come only from api.sdks —
no OpenAPI convention lists installable SDKs. A section with nothing to show
is left out.
A hand-written overview.mdx at the same path still wins. Specs listed under
openapi in syntext.json and specs added in the dashboard both get the
overview, the examples column and the API Reference sidebar grouped by tag,
and their links honour the entry's prefix. v1 pages are unchanged.
Try it on doc engine v2
On a doc engine v2 site, every endpoint page has a Try
it button in the endpoint bar that opens the request console as a dialog. It's
shown when features.playground is
on (the default) and features.endpointBarAction is tryIt (the default).
Linking to a page with #try in the URL opens it on load, and so does changing
the hash to #try on an open page.
A long path in the endpoint bar wraps after a slash (or a hyphen), never in the middle of a segment. On tablets it wraps inside the bar rather than scrolling under Try it.
The dialog puts the request on the left and the response on the right; on narrow windows they stack, and on phones it's a full-screen sheet. Its header shows the method, the path as you fill it in, the server selector, Copy as code and a close button. Escape closes it and returns focus to Try it.
The dialog is drawn in your site's look. Its frame, section labels, fields,
tabs and Send request button follow the
API style of your preset (appearance.components.api),
the request editor and response body follow the code block style
(appearance.components.code), and your accent, radius, fonts and light or
dark mode apply as they do everywhere else. Change any of them in Appearance
and the dialog changes with the page.
The request
The console is built from the request the page documents — the same page content the generated request samples read:
ParamFields,
with their descriptions and placeholders. Optional ones can be removed and
added back, and readers can add their own rows. The documented
Content-Type and the auth header are filled in by the console.multipart/form-data, or a raw body with Content-Type: image/png;type="file" field, which makes the body multipart;A page that documents more than one (a multipart upload or a raw file, say) gets a body-type switcher, in the order the page gives them.
| Body type | What the reader fills in |
|---|---|
| JSON | A Form view (typed inputs, value menus, switches, nested groups, arrays with add and remove, required markers, examples and defaults as placeholders) and a JSON view with Format. The two stay in sync; Fill example values fills the form from the page's examples. The JSON view is a highlighted code editor: Tab indents (Esc, then Tab, moves on), pasted JSON is formatted, and invalid JSON is flagged with its line and column |
| Multipart form | The fields, plus a file picker with drag and drop |
| Raw file | One file; its own type is sent as the Content-Type |
| URL-encoded form | The fields |
| Raw text | A text editor |
Send stays off until the request is complete, and the console says why —
for example Fill in projectId and name, and add your session token to
send. When only the credential is missing, Send without it sends the
request anyway. DELETE still needs confirmation: the reader types DELETE
before the request is sent.
Copy as code copies the request as it's filled in, in any of the 15
request languages — the site's
requestLanguages first, then the rest. The credential is replaced by a
placeholder (<jwt>, <token> or <api-key>; YOUR_API_KEY in a query
string), so nothing the reader typed is copied. With no credential declared,
the copied code has no auth header.
The response
401, 403, 404, 413, 415 and 429.What's sent
Requests go straight from the reader's browser to your API, with no
cookies or other credentials attached, and only to the page's own http(s)
servers. Your API must allow CORS from the doc site.
Servers, in order:
servers, when it lists more than onebaseUrls in syntext.json, when it lists more than onebaseUrl, else the first of either listAn endpoint with no http(s) server gets no console.
Auth: the page's frontmatter auth, then auth in syntext.json
(Declaring auth). Nothing
declared means no credential: no field, and none sent. auth: none on a page
turns a site-wide credential off for a public endpoint. Labels and
placeholders come only from the declaration, never from the page's text. A
parameter with the credential's name is left out of the form, since the
credential fills it.
OpenAPI pages say a request body's content type under Body parameters when it
isn't JSON (for example, Content type: multipart/form-data), and
format: binary fields are shown with type file (file[] for arrays), so
Try it offers a file picker for them.
Response status dropdown with per-status messages
The response panel groups examples by status code in a dropdown (200, 400, 404, …). When a response example has a name in the spec (a key in content.examples), that name appears as a label in the panel header for the selected status — e.g. selecting 404 shows "CustomerNotFound" next to the copy button. If the spec provides no example name, no label is shown. Multiple named examples for the same status each get their own dropdown entry (404 · CustomerNotFound, 404 · KycNotFound).
Statuses without an authored example still appear in the dropdown: a skeleton example is synthesized from the response schema and merged alongside your authored ones. Authoring an example for one status (say 400) never hides the synthesized examples for the others — entries are sorted by status code, authored examples always win for their own status.
Deprecated operations
Operations with deprecated: true render a "Deprecated" badge next to the page title (and next to the endpoint in the overview list). The generated page's frontmatter also carries deprecated: true, so you can detect deprecated pages programmatically.
Sidebar group labels
Endpoints are grouped in the sidebar by their spec tags. The group label is chosen as follows:
tags array with an x-displayName, that display name is usedname is used verbatim — including its casingrisk-scoring becomes "Risk Scoring", and common acronyms are fully uppercased — KYC, FX, API, SDK, URL, ID, S2S, KYB, 2FA, SSO, AML, IBAN, ACH, SEPA (so kyc becomes "KYC", not "Kyc")Humanizing only applies to all-lowercase tag names. If you want a specific label for a lowercase tag, declare it in the top-level tags array with an x-displayName.
Page URLs, and what happens when two endpoints collide
Without a prefix on the openapi entry, each endpoint page's URL is
/api-reference/<group>/<id>, where <id> is the operation's operationId if
it declares one, and otherwise its method and
path reduced to lowercase letters, digits and hyphens — GET /v1/users/{id}
becomes get-v1-users-id.
That reduction is lossy, so two endpoints can arrive at the same id:
| Endpoints | Both reduce to |
|---|---|
GET /v1/users/{id} and GET /v1/users/id | get-v1-users-id |
GET /v1/user_profile and GET /v1/user-profile | get-v1-user-profile |
| Any two paths written in a non-Latin script | the same id |
When that happens, the first endpoint in the spec keeps the URL it has today, and each later one is given a distinct URL with a short suffix. The suffix is derived from the endpoint's own method and path, so it is the same on every build and the page's URL does not move between deploys.
An operationId is used as a single path segment. One containing / or \,
or consisting of dots, is cleaned up rather than used as written.
To control these URLs yourself on an entry without a prefix, give each
operation an explicit operationId — it is used verbatim, so two operations
with distinct operationIds never collide. A prefixed entry always uses
{prefix}/{method}-{path}.
Auto-Sync on Release
The simplest sync needs no pipeline step: commit the spec to your docs
repository and list it under openapi in
syntext.json. Every build re-reads it, so pushing a changed spec is the sync.
To push a spec from CI instead — say, one generated by your API's build —
call the import endpoint with a project API key with the build scope:
The site redeploys with the new spec, which counts toward your monthly build quota.
Inspecting What's Imported
Listing works with a read key. To remove a spec and its generated pages: DELETE /v1/projects/{projectId}/openapi (build scope).
Combining with Hand-Written Content
Generated pages cover the what; write guides for the why. Link generated endpoint pages from your guides, and use annotation coverage to make sure code-level docs keep pace too.
GraphQL, gRPC, and AsyncAPI schemas are also supported via the same import pattern (/graphql, /grpc, /asyncapi endpoints).