Mock server

rapidoc mock serves every local spec of the portal on one port, each under /<api id> (a version other than the default under /<api id>/<version>). Readers can press Try before the API exists, and you can demo who may call what with real tokens.

npm install -D @rapidoc/mock
npx rapidoc mock

http://localhost:4010/bookstore   → specs/bookstore.yaml

List the mock as a server in the spec, and the reference pages’ Try calls it:

servers:
  - url: http://localhost:4010/bookstore
    description: Local mock

This site’s example API does exactly that: run npm run mock in its repository and Try answers. Run workflow on a workflow diagram uses the same server, so whole workflows run with no backend.

What it answers

Examples first: the response’s example from the spec, else data generated from the schema (patterns, formats, enums, ranges). Generated data is the same on every run for a given --seed.
Validated requests: parameters and JSON, form and multipart bodies are checked against the spec. A bad request gets 400 with the list of problems.
CORS for any origin, so a portal on another port can call it.

Choosing a response

Request header	Effect
`Prefer: code=404`	The documented `404` response (else `4XX`, else `default`).
`Prefer: example=empty`	The media type’s example named `empty`.
`Prefer: dynamic=true`	Generated data even when there is an example.

Applied preferences come back in Preference-Applied. GET / lists the APIs served.

Real token checks

Each operation’s security is enforced:

Scheme	Check
OAuth 2, OpenID Connect, HTTP bearer	The token must be a JWT signed by your issuer, unexpired and for your audience, else `401`. It must grant the operation’s scopes in its `scope`, `scp` or `permissions` claim, else `403` with `WWW-Authenticate: Bearer error="insufficient_scope"`.
API key	The header, query parameter or cookie must be present.
HTTP basic	Credentials must be present.
`security: []` or none	Open.

npx rapidoc mock --issuer https://acme.us.auth0.com/ --audience https://api.acme.com

Without --issuer, any bearer token passes and scopes aren’t checked. Combined with Try with the reader’s token, signed-in readers see 200 or 403 depending on their own permissions.

Options

Option	Variable	Meaning
`--issuer <url>`	`RAPIDOC_MOCK_ISSUER`	OpenID Connect issuer whose access tokens are accepted.
`--audience <id>`	`RAPIDOC_MOCK_AUDIENCE`	`aud` the tokens must have.
`--port <number>`		Default `4010`.
`--host <host>`		Default `0.0.0.0`.
`--seed <number>`		Seed for generated data. Default `1`.

Without a portal

The mock also works on plain spec files:

npx rapidoc mock ./specs                      # every OpenAPI file in the folder
npx rapidoc mock orders.yaml billing.json     # these files

Each spec is served under its file name: orders-api.yaml is /orders-api. The mapping is printed at start. This needs only @rapidoc/cli and @rapidoc/mock, not the portal.