The try-it client
A real request, sent by the reader's own browser.
Every operation page carries a client: pick a server, fill the parameters, edit the body, send it.
No proxy, ever
The request is made by the reader's browser with fetch, straight to the server
they chose. Nothing passes through the site that serves the documentation.
That is a decision, not a limitation. A proxy would mean the reader's credentials travelling to a third party — and the documentation site is a third party to the API it documents. What it costs is that an API without CORS cannot be called from here; the client says so rather than failing silently.
Servers
Every server the document declares, with its variables as fields. An operation
that overrides servers gets its own list.
Authentication
One box per scheme the operation's requirement names.
| Scheme | What the client does |
|---|---|
apiKey in header or query | Sends the value where the document says |
http bearer | Asks for the token, sends Authorization: Bearer … |
http basic | Asks for user and password, encodes them |
oauth2, openIdConnect | Asks for the token — both end in a bearer header |
apiKey in cookie | Says it cannot. A page may not set a cookie |
mutualTLS | Says it cannot. A page has no client certificate |
!IMPORTANT What you type into an authentication box stays in the tab, is never stored, and is sent only to the server you chose.
A value to start from
A scheme may name one, and the client fills the field with it:
securitySchemes:
bearer:
type: http
scheme: bearer
x-duxt-example: demo-token
An extension, because OpenAPI has no field for it: a security scheme says where a credential goes, never what one looks like. It is the difference between a reader seeing a client and seeing it work — a demo endpoint that answers to any token can say so, instead of asking them to invent a value first.
!CAUTION A published file. Put a demo value here, never a real credential.
A cookie parameter is deliberately not built into the request. Cookie is a
forbidden header name for fetch: a browser drops it with no error and nothing in
the console, so the request would quietly lack the credential while the curl
sample beside it showed the header present — the one place a reader would look to
confirm. The client says the cookie cannot be set from a page instead, so what is
sent and what is shown are the same request again.
The body
Two views of the same value, and the reader picks once for the whole site:
- Form — a field per property, drawn from the schema, with the constraints it declares.
- JSON — an editor, for a body the form cannot draw. A body that is not valid JSON yet is sent as written rather than blocked.
A schema too loose to draw as a form says so and offers the editor.
The editor is CodeMirror, loaded on demand — a page with no endpoint downloads none of it. It is deliberately not Monaco: an editor whose workers and megabytes every consumer site carries, for a box that holds ten lines of JSON, is the wrong trade for a package.
The response
Status, headers and body, below the editor. That is also why the code samples beside it stop at the request — see Request samples.
When it does not arrive
fetch rejects with a bare TypeError for a CORS refusal, a DNS failure and an
offline network alike, so the client cannot tell the reader which of the three it
was. It says the request did not reach the server, and names the two likely
reasons, rather than guessing at one.