/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Recipes Recipe: Sync Your OpenAPI Spec

Recipe: Sync Your OpenAPI Spec

Keep generated API reference pages in sync with your OpenAPI spec on every release.

19 min read

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.

Commit your specs next to your docs and list them in syntext.json:

json
{
"openapi": [
{ "path": "./openapi/users.yaml", "prefix": "api-reference/users" },
{ "path": "./openapi/orders.yaml", "prefix": "api-reference/orders" }
]
}

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.

From a URLInline document
curl -X POST https://api.syntext.dev/v1/projects/$PROJECT_ID/openapi \
-H "Authorization: Bearer $SYNTEXT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "source": "url", "url": "https://api.acme.com/openapi.json" }'

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 base64
•
apiKey — 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: cookie
•
oauth2 and openIdConnect — a token the reader already has, sent as a Bearer token; the console says so

A 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.

yaml
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Api-Key

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:

json
{
"auth": { "name": "Api-Key" },
"openapi": [
{ "path": "./openapi.yaml", "prefix": "api-reference" }
]
}

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:

json
{
"headers": [
{ "name": "X-Idempotency-Key", "required": true, "description": "Unique key to safely retry requests" }
]
}

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.

yaml
paths:
/accounts:
post:
summary: Create account
description: |
Creates a new account for the authenticated user.
## Idempotency
Pass an `Idempotency-Key` header to safely retry:
- Keys expire after 24 hours
- Reusing a key returns the original response

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 description
•
oneOf / 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:

yaml
content:
application/json:
examples:
Personal account:
value: { "type": "personal", "email": "jo@example.com" }
Business account:
value: { "type": "business", "taxId": "DE123456789" }

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:

json
{
"baseUrls": [
{ "url": "https://api.example.com", "description": "Production" },
{ "url": "https://sandbox.example.com", "description": "Sandbox" }
]
}

Plain strings work too: "baseUrls": ["https://api.example.com", "https://sandbox.example.com"].

Alternatively, declare servers in the spec itself:

yaml
servers:
- url: https://api.example.com
description: Production
- url: https://sandbox.example.com
description: Sandbox

Or, if one spec needs different hosts than the rest of the site, set servers on that openapi entry:

json
{
"openapi": [
{
"path": "./specs/users.yaml",
"prefix": "api-reference/users",
"servers": [
{ "url": "https://users.example.com", "description": "Production" },
{ "url": "https://users-sandbox.example.com", "description": "Sandbox" }
]
}
]
}

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:

1.
the server marked x-syntext-sandbox: true, if one is
2.
otherwise the first server — your live API

Mark the sandbox with the same key wherever you declare servers. In the spec:

yaml
servers:
- url: https://api.example.com
description: Production
- url: https://sandbox.example.com
description: Sandbox
x-syntext-sandbox: true

In syntext.json baseUrls, or an openapi entry's servers (they replace the spec's servers, so mark it there):

json
{
"baseUrls": [
{ "url": "https://api.example.com", "description": "Production" },
{ "url": "https://sandbox.example.com", "description": "Sandbox", "x-syntext-sandbox": true }
]
}

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:

•
Introduction: info.description, then a table of your tags.
•
Base URL: a selector built from servers, with a copy button.
•
Authentication: one card per security scheme (bearer, basic, API key in a header, query or cookie, OAuth and OpenID Connect) with the scopes your endpoints use. An auth block in syntext.json replaces the schemes.
•
Errors: an example error body, then every 4xx and 5xx status declared across your endpoints.
•
Rate limits: the rate-limit headers your responses declare — 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.
•
Pagination: the request parameters named by 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.
•
Endpoints: grouped by tag, each linking to its page.
yaml
paths:
/projects:
get:
parameters:
- { name: cursor, in: query, schema: { type: string } }
- { name: limit, in: query, schema: { type: integer, default: 20 } }
x-speakeasy-pagination:
type: cursor
inputs:
- { name: cursor, in: parameters, type: cursor }
- { name: limit, in: parameters, type: limit }
outputs: { nextCursor: $.nextCursor }
responses:
"200":
headers:
X-RateLimit-Remaining:
description: Requests left this minute
schema: { type: integer }

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:

•
Credential — only what the page declares (see Auth below), labelled as declared, with its description underneath. With several declared, a chooser picks one. With none declared, there's no credential field at all. It's masked, with a toggle to show it, and it's never stored: it lives only as long as the page.
•
Path, query and header parameters come from the page's 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.
•
Body — how it's sent is read from the page:
•
a MIME type written in code under the body heading — Content type: multipart/form-data, or a raw body with Content-Type: image/png;
•
otherwise a type="file" field, which makes the body multipart;
•
otherwise body fields mean JSON.

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 typeWhat the reader fills in
JSONA 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 formThe fields, plus a file picker with drag and drop
Raw fileOne file; its own type is sent as the Content-Type
URL-encoded formThe fields
Raw textA 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

•
A status pill with its reason, the time taken and the size.
•
Body and Headers tabs. JSON bodies are highlighted, with a copy button; images are previewed; other binary bodies are offered as a download.
•
Hints for 401, 403, 404, 413, 415 and 429.
•
A network or CORS failure is explained in the dialog: the request went straight from the browser, and the API (or the network) didn't let it through.

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:

1.
the page's frontmatter servers, when it lists more than one
2.
baseUrls in syntext.json, when it lists more than one
3.
otherwise a single URL: the page's baseUrl, else the first of either list

An 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.

Endpoints are grouped in the sidebar by their spec tags. The group label is chosen as follows:

1.
If the tag is declared in the spec's top-level tags array with an x-displayName, that display name is used
2.
Otherwise, a declared tag's name is used verbatim — including its casing
3.
Tags that appear only on operations (not declared at the top level) get a humanized label: risk-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")
Note

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.

yaml
tags:
- name: accounts
x-displayName: Account Management # sidebar shows "Account Management"
- name: Payments # declared — shown verbatim as "Payments"
# operations tagged `kyc` without a declaration → shown as "KYC"

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:

EndpointsBoth reduce to
GET /v1/users/{id} and GET /v1/users/idget-v1-users-id
GET /v1/user_profile and GET /v1/user-profileget-v1-user-profile
Any two paths written in a non-Latin scriptthe 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.

Note

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:

yaml
name: Sync API docs
on:
push:
branches: [main]
paths: ['openapi.json']
jobs:
sync:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Push spec to Syntext
run: |
curl -fsS -X POST https://api.syntext.dev/v1/projects/${{ vars.SYNTEXT_PROJECT_ID }}/openapi \
-H "Authorization: Bearer ${{ secrets.SYNTEXT_API_KEY }}" \
-H "Content-Type: application/json" \
-d "$(jq -n --rawfile c openapi.json '{source: "inline", content: $c}')"

The site redeploys with the new spec, which counts toward your monthly build quota.

Inspecting What's Imported

bash
# List imported specs
curl https://api.syntext.dev/v1/projects/$PROJECT_ID/openapi/specs \
-H "Authorization: Bearer $SYNTEXT_API_KEY"
# List generated endpoints
curl https://api.syntext.dev/v1/projects/$PROJECT_ID/openapi/endpoints \
-H "Authorization: Bearer $SYNTEXT_API_KEY"

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.

Note

GraphQL, gRPC, and AsyncAPI schemas are also supported via the same import pattern (/graphql, /grpc, /asyncapi endpoints).

Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext