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

DEV Community: Mockzilla

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

Two ways it fails

Why

What you write instead

This is not a bug report

If you do have a spec