DEV Community: Mockzilla

Reimporting Stripe's new OpenAPI spec into Mockoon left 559 routes on the old API

Mockzilla — Tue, 15 Sep 2026 12:18:08 +0000

Disclosure: I work on Mockzilla, which competes with Mockoon. Everything below
was run on one laptop, and there is a link to the longer comparison at the end.

Mockoon is a quick way to get a Stripe mock running. Import Stripe's OpenAPI
spec into the desktop app, fix the responses your tests care about, and every
route answers on localhost:3000.

Then Stripe ships a new API version, and you import the new spec over the old
one.

What basil moved

In March 2025 Stripe released an API version called basil. It moved
current_period_start and current_period_end from the subscription to each
subscription item. If your code handles subscriptions, it probably reads one of
them.

The reimport

When you import a spec, Mockoon converts it into its own file format, and from
then on that file is what you edit and run. Stripe's spec is 6.4 MB. The Mockoon
file it turns into is 30.5 MB. Mockoon's own documentation calls import "a good
starting point but not a way to share your mock APIs".

Reimport only adds. From the same docs: "No existing routes or responses will be
modified or deleted".

I imported the Stripe spec from before basil, then reimported the basil one.
Mockoon added 2 new routes. The other 559 stayed as they were, this one
included:

$ curl -s localhost:3000/v1/subscriptions/sub_123 \
    | jq '{current_period_end, item_period_end: .items.data[0].current_period_end}'
{
  "current_period_end": 13345,
  "item_period_end": null
}

Code already updated for basil reads the item and gets null. Older code
reads the top-level field, and its tests pass against a field Stripe no longer
sends. Two endpoints that basil removed still answer 200.

To get a changed route from the new spec, you delete the route and import
again. That also deletes whatever you had edited in it.

The empty strings

You will have edited some routes, because Mockoon fills Stripe's text fields
with empty strings. Create a customer the way a test would:

$ curl -s localhost:3000/v1/customers -d email=jenny@example.com -d "name=Jenny Rosen" \
    | jq -c '{id, object, email, name, currency}'
{"id":"","object":"customer","email":"","name":"","currency":""}

Across the whole Stripe mock, 223,537 fields are empty, and currency alone is
empty in 4,641 places. The empty id breaks the next step of the test: fetching
that customer requests /v1/customers/, and that route answers with the
customer list.

The fix is per route: open the route and edit its response body, for example
with a template helper that copies the email from the request. A route you fixed
stays on the old spec after every reimport.

Start-up and memory

Mockoon handles the full Stripe spec. Prism, for one, did not open a port on it
in 30 minutes. I ran both tools on Stripe's current spec, three runs each, timed
from launch to first response:

Stripe, 6.4 MB	Mockoon CLI 9.8.0	Mockzilla 2.8.16
First response, from the spec	1,335 to 1,386 ms	210 to 242 ms
Memory, warm	477 to 487 MiB	194 MiB
First response, from the converted file	457 to 488 ms at 280 MiB	no such file
What you install	Node.js and 252 npm packages, 103 MB	one 40 MiB binary

The CLI converts the spec again on every start, which is where the extra second
goes. On a laptop none of this matters much. CI pays it in every job, and
Mockoon's GitHub Action spent 8 to 10 seconds on the npm install alone.

When Mockoon is the better choice

If your API has no OpenAPI spec, use Mockoon. You build the routes by hand in
its desktop app and set each response by clicking.

A Mockoon route can also hold several responses and pick one by rule, such as a
402 when the request contains pm_card_visa_chargeDeclined, Stripe's test
payment method for a declined card. Callbacks send a follow-up request after a
call, which is how you fake a webhook. A record you create with POST comes back
on GET. Mockzilla needs Go code to pick a response by request, keeps no data
between calls, and does not read the Swagger 2.0 files Mockoon accepts.

If your mock starts from a spec

The other approach is a mock server that reads the spec on every start.
Replacing the file is the update. Given the basil spec, Mockzilla puts the
period fields on the item and answers 404 on the two removed endpoints.

The fixes go in a separate file next to the spec, keyed by field name:

currency: ["usd", "eur", "gbp"]
in-response:
  email: "request:email"
  name: "request:name"

One currency line covers every currency field in Stripe's responses. When
Stripe ships the next version you replace the spec and keep this file.

The full comparison has both tools side by side, latency and error settings,
replay, what CI looks like on each side, and the prices:

Mockoon alternative: keep your mock API in sync with your OpenAPI spec

Prism spent 30 minutes on Stripe's OpenAPI spec and never opened a port

Mockzilla — Fri, 11 Sep 2026 10:04:38 +0000

Disclosure: I work on Mockzilla, which competes with Stoplight Prism.
Everything below was measured on my laptop, and there is a link to the longer
comparison at the end.

Prism is the default answer to "I need to mock this OpenAPI spec", and for most
specs it is the right one. Install it, point it at a document, every operation
in the file answers.

npm install -g @stoplight/prism-cli
prism mock openapi.yml

Then I gave it Stripe.

The run

Stripe publishes its API as an OpenAPI document. The copy I used is 6.0 MB, 414
paths and 587 operations. Large, but not unusual: GitHub's is 8.8 MB.

$ prism mock stripe.yml
[CLI] …  awaiting  Starting Prism…

Nothing followed it. Thirty minutes on it was still that one line, the
process pinned at 100% of a core with 216 MiB resident and nothing listening on
port 4010. That is where I stopped it.

Handing it JSON instead does not help. The same document as stripe.json, same
machine: no listener after fifteen minutes, at 274 MiB. There is no flag for
this and nothing was misconfigured.

Where the time goes

Not parsing. Python's YAML parser loads the same file in 5.3 seconds.

It goes on resolution. Stripe's document carries 1,286 component schemas with
3,700 $refs pointing into them, and Prism walks all of that before it binds a
port. A spec with a few hundred inline schemas never shows you this.

The file itself is servable. The mock server I work on opens a port on the same
document in 195 ms and answers the first request at 364 ms.

What it costs on a spec that does work

Twilio Verify: 29 paths, 53 operations, 173 KB of YAML. Installed natively,
three runs.

	Prism 5.16.0
Start to first response	509 to 531 ms
Memory, warm	191 to 199 MiB
What you install	210 npm packages, 68 MiB

Half a second and 200 MB is nothing on a laptop. A container that boots and
dies on every CI job pays it every time.

One process, one document

"A single Prism instance serves one OpenAPI document." Prism's documentation
says so, and what it recommends for a second document is a second process on a
second port with a reverse proxy in front of both:

services:
  proxy:
    image: caddy
    ports:
      - '8080:80'
    depends_on:
      - prism_1
      - prism_2
  prism_1:
    image: stoplight/prism:4
    command: mock -p 4010 --host 0.0.0.0 petstore-v2.yaml
  prism_2:
    image: stoplight/prism:4
    command: mock -p 4010 --host 0.0.0.0 petstore-v3.yaml

Most test suites talk to more than one vendor. Three of them is three Node
processes, three ports, a Caddyfile and something to supervise the lot, on
every developer machine and in every CI job. Each process holds its own copy of
its own document, so the 191 to 199 MiB above is per API rather than per
machine.

What Prism does better

Three things, and if you need the first one this post ends here.

Forcing a status code, per request. Prefer: code=404 on any call, or
?__code=404 if a header is awkward, and Prism serves that response out of the
document. Ask for a code the document does not declare and you still get the
status, with a Prism error body saying so. What I run has no per-request
equivalent.

Enforcing the document's security. Twilio Verify declares HTTP basic auth,
so Prism answers 401 with a WWW-Authenticate header until you send
credentials. Prism's behaviour is the contract-accurate one, and it catches a
client that forgot to send a token.

Older and stranger documents. OpenAPI 2.0, the version still called
Swagger, and Postman Collections. If your document has not been converted yet,
that decides it.

If your spec is the big kind

A mock server that reads the document at start-up and resolves all of it has a
ceiling, and Stripe's spec is above it. Worth knowing before you put prism mock in a CI job and find out from a timeout.

I wrote up the full comparison with both tools running the same specs, the
generated data either side, the per-request controls, and the prices:

Stoplight Prism alternative: an OpenAPI mock server with a URL

WireMock will not read your OpenAPI spec, and that is on purpose

Mockzilla — Fri, 04 Sep 2026 14:04:14 +0000

Disclosure: I work on Mockzilla, which competes with WireMock. Everything below
was run on my laptop today and every claim links to its source. There is a link
to the longer comparison at the end, and you can stop reading before it.

You have an OpenAPI document. You want a mock server. WireMock is what most
people find first, so you start the container and give it your spec.

It will not read it.

Two ways it fails

Drop the spec where WireMock keeps its stubs and start it:

docker run -d -p 8080:8080 -v "$PWD/wiremock:/home/wiremock" wiremock/wiremock:3.13.2

The container comes up. It also loaded nothing:

$ curl -s localhost:8080/__admin/mappings | jq .meta
{ "total": 0 }

WireMock reads .json from that directory and ignores everything else, so a
.yml spec sits there in silence. Convert it to JSON, which is the obvious next
move, and the container stops starting at all:

MappingFileException: Error loading file /home/wiremock/./mappings/openapi.json:
Unrecognized field "openapi" (class ...StubMappingCollection), not marked as ignorable

openapi is an unrecognized field.

Why

This is not an oversight. OpenAPI import is a WireMock Cloud feature and the
open source version has never had it. Somebody asked for it in August 2018, and the answer came the next morning from WireMock's creator:

I don't have any plans to open source MockLab's implementation at the moment.
I'd suggest if you want to work on this that you make it an extension.

MockLab was the earlier name of WireMock Cloud. Eight years on, the feature is
still on that side of the line.

What you write instead

One JSON file per stub, each holding a request matcher and a response. A
minimal one for a single endpoint runs about 25 lines, and it covers exactly
that endpoint. Ask for the next path along and you get Request was not matched.

Twilio Verify is a small API: 29 paths, 53 operations. That is 53 stub files,
and every field in them is a response shape you looked up by hand and typed.
GitHub's public API description is 551 paths and 845 operations.

Then there is the part that shows up later. Your spec and your stubs are now two
descriptions of the same API, maintained at different times, and only one of
them is what the service implements. Somebody has published a GitHub Action
called WireMock OpenAPI Validator
whose entire job is checking stub mappings against a spec in CI, and it
describes itself as "perfect for ensuring your mocks stay in sync with your API
contracts".

This is not a bug report

WireMock's unit of work is a stub: one matcher, one canned response. A spec is
not a stub, so the tool is consistent with what it is. The project is also in
good health, with 3.13.2 shipped in November 2025 and v4 in beta.

Three things it does that a spec-driven mock does not. WireMock runs inside your
test process, in Java and through wrappers in .NET, Python, Go and Rust. You can
assert on the requests your code sent, so verify(getRequestedFor(...)) fails
the test when the call never happened. And its scenarios move a stub between
states, so the same call answers differently the second time.

If you need any of those, none of this matters and WireMock is your answer.

If you do have a spec

The alternative is a server that takes the document as its input, so the mock
and the contract are one file. I wrote up the full comparison with both tools
running the same API side by side, including the measurements, the per-endpoint
cost, and where WireMock still wins:

WireMock alternative: mock an OpenAPI spec without writing stubs