Getting Started
Import & Export via OpenAPI
Already have a spec for the API you're mocking? Skip typing out routes by hand — import an OpenAPI 3.x document (JSON or YAML) and MockBase turns every operation into a route automatically. Going the other way, export any mock as a spec other tools can open.
Importing a spec
From the Dashboard, choose Import OpenAPI instead of creating a mock manually. You can also import into a mock you already have, to add more routes to it later without starting over. There are three ways to supply the document:
- Paste or edit it in the built-in editor, with JSON and YAML syntax highlighting. YAML indentation mistakes are the classic way to lose an afternoon, so the document is parsed as you type.
- Choose a file from your machine (
.json,.yaml,.yml). It loads into the same editor, so you can fix something before importing rather than after. - Import from a URL — paste a link to a published spec and MockBase fetches it server-side. The URL has to be reachable on the public internet: one pointing at your own machine or a private network is refused.
You see what you'll get, first
Before anything is imported, the panel reports what the document actually contains: its title, spec version, how many paths and operations it declares, and the list of method-and-path pairs that will become routes. If it can't be parsed, you get the parser's own message including the line and column — not a generic failure after the fact.
A Swagger 2.0 document is flagged rather than quietly half-imported: its routes come through, but response bodies live under schema instead of OpenAPI 3's content, so the examples come out empty. Converting it to OpenAPI 3 first gets you full bodies.
How a response is chosen
For each operation, MockBase picks a response like this:
- The lowest 2xx status the operation declares becomes the route's status code (falling back to
default, then whatever's listed first, if there's no 2xx). - The response body comes from the operation's own
example, or its firstexamplesentry, when either is present. - Otherwise, MockBase synthesizes a body from the response schema — objects and arrays are rebuilt field by field (one item deep for arrays), and each scalar gets a placeholder matching its declared type and format: an ISO date-time for
format: date-time, a UUID forformat: uuid, an address-shaped string forformat: email, and so on. Internal$refreferences (#/components/...) are resolved; references to another file are not. - A status code your spec declares that MockBase doesn't support (see the list in Quickstart) falls back to
200for that route rather than failing the whole import.
Exporting a mock
Open a mock and choose Export, or call:
GET /api/v1/mocks/<mock_id>/export?format=json
GET /api/v1/mocks/<mock_id>/export?format=yamlto download it as an OpenAPI 3.0 document. The document is built entirely from what you already configured — you are never asked to describe the same API twice:
- Every route survives. Routes sharing a method and path become one operation with one response per status code. Since conditional matching makes several routes per endpoint the normal way to model one, an operation that reported only one of them would describe an API that doesn't exist.
- Schemas are inferred from your example bodies. Types, formats (
date-time,uuid,email,uri), and required fields are derived from what the route actually returns, then hoisted intocomponents/schemas. Identical shapes are declared once and referenced by$refeverywhere they appear, so the document stays editable in other tools instead of being a wall of duplicated inline objects. - Parameters come from your match conditions. A condition on a query value or header is already a declaration that the parameter exists and is constrained, so it exports as a required parameter with a description of what it demands ("Must equal
staging."). A condition on the request body describes the request body instead. - Every operation gets an
operationId, derived from its method and path, because that is what code generators use to name functions. - A binary or XML route declares its media type rather than a JSON schema, since that is the real contract.
The document's servers entry points straight at the mock's own public URL, so it opens correctly in Swagger UI, Postman, or a code generator without any editing first.
What the export can't capture is behavior that varies per request: dynamic templates, chaos injection, rate limits, and stateful CRUD have no single "example response" to declare. graphql_operation and soap_body conditions aren't exported as parameters either — they address a payload's contents, which OpenAPI has no parameter-level vocabulary for.
Trial limits still apply
Importing obeys the same anonymous limits as creating a mock by hand. If your spec would generate more routes than your plan allows, MockBase doesn't reject it — it creates the mock with as many routes as fit and reports how many it dropped via an X-Mockbase-Routes-Dropped response header, so you always get something to start from.