MockServer supports OpenAPI v3.0 specifications in either JSON or YAML format.
Note: MockServer uses the swagger-parser library which supports OpenAPI 3.0.x. OpenAPI 3.1 specifications may not be fully supported — in particular, features introduced in 3.1 (such as $ref siblings, type as an array, and the webhooks top-level key) may cause parsing errors. If you encounter validation errors, ensure your specification conforms to OpenAPI 3.0.x.
OpenAPI specifications can be used in request matchers for
OpenAPI specifications can also be used to generate expectations with example responses.
MockServer supports open api expectations containing the follow fields:
For each open api expectations MockServer creates multiple request matcher expectations as follows:
If an OpenAPI specification is submitted with operation filtering as follows:
{
"specUrlOrPayload": "https://raw.githubusercontent.com/mock-server/mockserver-monorepo/master/mockserver/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json",
"operationsAndResponses": {
"showPetById": "200",
"createPets": "500"
}
}Then the following expectations are created:
{
"priority": 0,
"httpRequest": {
"specUrlOrPayload": "https://raw.githubusercontent.com/mock-server/mockserver-monorepo/master/mockserver/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json",
"operationId": "showPetById"
},
"httpResponse": {
"statusCode": 200,
"headers": {
"content-type": [
"application/json"
]
},
"body": {
"id": 0,
"name": "some_string_value",
"tag": "some_string_value"
}
},
"times": {
"unlimited": true
},
"timeToLive": {
"unlimited": true
}
}{
"priority": 0,
"httpRequest": {
"specUrlOrPayload": "https://raw.githubusercontent.com/mock-server/mockserver-monorepo/master/mockserver/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json",
"operationId": "createPets"
},
"httpResponse": {
"statusCode": 500,
"headers": {
"content-type": [
"application/json"
]
},
"body": {
"code": 0,
"message": "some_string_value"
}
},
"times": {
"unlimited": true
},
"timeToLive": {
"unlimited": true
}
}new MockServerClient("localhost", 1080)
.upsert(
openAPIExpectation(
"https://raw.githubusercontent.com/mock-server/mockserver-monorepo/master/mockserver/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json"
)
);var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).openAPIExpectation({
"specUrlOrPayload": "https://raw.githubusercontent.com/mock-server/mockserver-monorepo/master/mockserver/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json"
}).then(
function () {
console.log("expectation created");
},
function (error) {
console.log(error);
}
);See REST API for full JSON specification
curl -v -X PUT "http://localhost:1080/mockserver/openapi" -d '{
"specUrlOrPayload": "https://raw.githubusercontent.com/mock-server/mockserver-monorepo/master/mockserver/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json"
}'See REST API for full JSON specification
Map<String, String> operationsAndResponses = new HashMap<>();
operationsAndResponses.put("showPetById", "200");
operationsAndResponses.put("createPets", "500");
new MockServerClient("localhost", 1080)
.upsert(
openAPIExpectation(
"https://raw.githubusercontent.com/mock-server/mockserver-monorepo/master/mockserver/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json",
operationsAndResponses
)
);var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).openAPIExpectation({
"specUrlOrPayload": "https://raw.githubusercontent.com/mock-server/mockserver-monorepo/master/mockserver/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json",
"operationsAndResponses": {
"showPetById": "200",
"createPets": "500"
}
}).then(
function () {
console.log("expectation created");
},
function (error) {
console.log(error);
}
);See REST API for full JSON specification
curl -v -X PUT "http://localhost:1080/mockserver/openapi" -d '{
"specUrlOrPayload": "https://raw.githubusercontent.com/mock-server/mockserver-monorepo/master/mockserver/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json",
"operationsAndResponses": {
"showPetById": "200",
"createPets": "500"
}
}'See REST API for full JSON specification
new MockServerClient("localhost", 1080)
.upsert(
openAPIExpectation(
"file:/Users/jamesbloom/git/mockserver/mockserver/mockserver-core/target/test-classes/org/mockserver/openapi/openapi_petstore_example.json"
)
);var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).openAPIExpectation({
"specUrlOrPayload": "file:/Users/jamesbloom/git/mockserver/mockserver/mockserver-core/target/test-classes/org/mockserver/openapi/openapi_petstore_example.json"
}).then(
function () {
console.log("expectation created");
},
function (error) {
console.log(error);
}
);See REST API for full JSON specification
curl -v -X PUT "http://localhost:1080/mockserver/openapi" -d '{
"specUrlOrPayload": "file:/Users/jamesbloom/git/mockserver/mockserver/mockserver-core/target/test-classes/org/mockserver/openapi/openapi_petstore_example.json"
}'See REST API for full JSON specification
new MockServerClient("localhost", 1080)
.upsert(
openAPIExpectation("org/mockserver/openapi/openapi_petstore_example.json")
);var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).openAPIExpectation({
"specUrlOrPayload": "org/mockserver/openapi/openapi_petstore_example.json"
}).then(
function () {
console.log("expectation created");
},
function (error) {
console.log(error);
}
);See REST API for full JSON specification
curl -v -X PUT "http://localhost:1080/mockserver/openapi" -d '{
"specUrlOrPayload": "org/mockserver/openapi/openapi_petstore_example.json"
}'See REST API for full JSON specification
new MockServerClient("localhost", 1080)
.upsert(
openAPIExpectation(FileReader.readFileFromClassPathOrPath("/Users/jamesbloom/git/mockserver/mockserver/mockserver-core/target/test-classes/org/mockserver/openapi/openapi_petstore_example.json"))
);var fs = require('fs');
try {
var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).openAPIExpectation({
"specUrlOrPayload": fs.readFileSync("/Users/jamesbloom/git/mockserver/mockserver/mockserver-core/target/test-classes/org/mockserver/openapi/openapi_petstore_example.json", "utf8")
}).then(
function () {
console.log("expectation created");
},
function (error) {
console.log(error);
}
);
} catch (e) {
console.log('Error:', e.stack);
}See REST API for full JSON specification
curl -v -X PUT "http://localhost:1080/mockserver/openapi" -d "{
\"specUrlOrPayload\": `cat /Users/jamesbloom/git/mockserver/mockserver/mockserver-core/target/test-classes/org/mockserver/openapi/openapi_petstore_example.json`
}"See REST API for full JSON specification
new MockServerClient("localhost", 1080)
.upsert(
openAPIExpectation("---\n" +
"openapi: 3.0.0\n" +
"info:\n" +
" version: 1.0.0\n" +
" title: Swagger Petstore\n" +
" license:\n" +
" name: MIT\n" +
"servers:\n" +
" - url: http://petstore.swagger.io/v1\n" +
"paths:\n" +
" /pets:\n" +
" get:\n" +
" summary: List all pets\n" +
" operationId: listPets\n" +
" tags:\n" +
" - pets\n" +
" parameters:\n" +
" - name: limit\n" +
" in: query\n" +
" description: How many items to return at one time (max 100)\n" +
" required: false\n" +
" schema:\n" +
" type: integer\n" +
" format: int32\n" +
" responses:\n" +
" '200':\n" +
" description: A paged array of pets\n" +
" headers:\n" +
" x-next:\n" +
" description: A link to the next page of responses\n" +
" schema:\n" +
" type: string\n" +
" examples:\n" +
" two:\n" +
" value: \"/pets?query=752cd724e0d7&page=2\"\n" +
" end:\n" +
" value: \"\"\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Pets'\n" +
" '500':\n" +
" description: unexpected error\n" +
" headers:\n" +
" x-code:\n" +
" description: The error code\n" +
" schema:\n" +
" type: integer\n" +
" format: int32\n" +
" example: 90\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Error'\n" +
" default:\n" +
" description: unexpected error\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Error'\n" +
" post:\n" +
" summary: Create a pet\n" +
" operationId: createPets\n" +
" tags:\n" +
" - pets\n" +
" requestBody:\n" +
" description: a pet\n" +
" required: true\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Pet'\n" +
" '*/*':\n" +
" schema:\n" +
" $ref: '#/components/schemas/Pet'\n" +
" responses:\n" +
" '201':\n" +
" description: Null response\n" +
" '400':\n" +
" description: unexpected error\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Error'\n" +
" '500':\n" +
" description: unexpected error\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Error'\n" +
" default:\n" +
" description: unexpected error\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Error'\n" +
" /pets/{petId}:\n" +
" get:\n" +
" summary: Info for a specific pet\n" +
" operationId: showPetById\n" +
" tags:\n" +
" - pets\n" +
" parameters:\n" +
" - name: petId\n" +
" in: path\n" +
" required: true\n" +
" description: The id of the pet to retrieve\n" +
" schema:\n" +
" type: string\n" +
" - in: header\n" +
" name: X-Request-ID\n" +
" schema:\n" +
" type: string\n" +
" format: uuid\n" +
" required: true\n" +
" responses:\n" +
" '200':\n" +
" description: Expected response to a valid request\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Pet'\n" +
" examples:\n" +
" Crumble:\n" +
" value:\n" +
" id: 2\n" +
" name: Crumble\n" +
" tag: dog\n" +
" Boots:\n" +
" value:\n" +
" id: 3\n" +
" name: Boots\n" +
" tag: cat\n" +
" '500':\n" +
" description: unexpected error\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Error'\n" +
" default:\n" +
" description: unexpected error\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Error'\n" +
"components:\n" +
" schemas:\n" +
" Pet:\n" +
" type: object\n" +
" required:\n" +
" - id\n" +
" - name\n" +
" properties:\n" +
" id:\n" +
" type: integer\n" +
" format: int64\n" +
" name:\n" +
" type: string\n" +
" tag:\n" +
" type: string\n" +
" example:\n" +
" id: 1\n" +
" name: Scruffles\n" +
" tag: dog\n" +
" Pets:\n" +
" type: array\n" +
" items:\n" +
" $ref: '#/components/schemas/Pet'\n" +
" Error:\n" +
" type: object\n" +
" required:\n" +
" - code\n" +
" - message\n" +
" properties:\n" +
" code:\n" +
" type: integer\n" +
" format: int32\n" +
" message:\n" +
" type: string\n")
);
}var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).openAPIExpectation({
"specUrlOrPayload": "---\n" +
"openapi: 3.0.0\n" +
"info:\n" +
" version: 1.0.0\n" +
" title: Swagger Petstore\n" +
" license:\n" +
" name: MIT\n" +
"servers:\n" +
" - url: http://petstore.swagger.io/v1\n" +
"paths:\n" +
" /pets:\n" +
" get:\n" +
" summary: List all pets\n" +
" operationId: listPets\n" +
" tags:\n" +
" - pets\n" +
" parameters:\n" +
" - name: limit\n" +
" in: query\n" +
" description: How many items to return at one time (max 100)\n" +
" required: false\n" +
" schema:\n" +
" type: integer\n" +
" format: int32\n" +
" responses:\n" +
" '200':\n" +
" description: A paged array of pets\n" +
" headers:\n" +
" x-next:\n" +
" description: A link to the next page of responses\n" +
" schema:\n" +
" type: string\n" +
" examples:\n" +
" two:\n" +
" value: \"/pets?query=752cd724e0d7&page=2\"\n" +
" end:\n" +
" value: \"\"\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Pets'\n" +
" '500':\n" +
" description: unexpected error\n" +
" headers:\n" +
" x-code:\n" +
" description: The error code\n" +
" schema:\n" +
" type: integer\n" +
" format: int32\n" +
" example: 90\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Error'\n" +
" default:\n" +
" description: unexpected error\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Error'\n" +
" post:\n" +
" summary: Create a pet\n" +
" operationId: createPets\n" +
" tags:\n" +
" - pets\n" +
" requestBody:\n" +
" description: a pet\n" +
" required: true\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Pet'\n" +
" '*/*':\n" +
" schema:\n" +
" $ref: '#/components/schemas/Pet'\n" +
" responses:\n" +
" '201':\n" +
" description: Null response\n" +
" '400':\n" +
" description: unexpected error\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Error'\n" +
" '500':\n" +
" description: unexpected error\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Error'\n" +
" default:\n" +
" description: unexpected error\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Error'\n" +
" /pets/{petId}:\n" +
" get:\n" +
" summary: Info for a specific pet\n" +
" operationId: showPetById\n" +
" tags:\n" +
" - pets\n" +
" parameters:\n" +
" - name: petId\n" +
" in: path\n" +
" required: true\n" +
" description: The id of the pet to retrieve\n" +
" schema:\n" +
" type: string\n" +
" - in: header\n" +
" name: X-Request-ID\n" +
" schema:\n" +
" type: string\n" +
" format: uuid\n" +
" required: true\n" +
" responses:\n" +
" '200':\n" +
" description: Expected response to a valid request\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Pet'\n" +
" examples:\n" +
" Crumble:\n" +
" value:\n" +
" id: 2\n" +
" name: Crumble\n" +
" tag: dog\n" +
" Boots:\n" +
" value:\n" +
" id: 3\n" +
" name: Boots\n" +
" tag: cat\n" +
" '500':\n" +
" description: unexpected error\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Error'\n" +
" default:\n" +
" description: unexpected error\n" +
" content:\n" +
" application/json:\n" +
" schema:\n" +
" $ref: '#/components/schemas/Error'\n" +
"components:\n" +
" schemas:\n" +
" Pet:\n" +
" type: object\n" +
" required:\n" +
" - id\n" +
" - name\n" +
" properties:\n" +
" id:\n" +
" type: integer\n" +
" format: int64\n" +
" name:\n" +
" type: string\n" +
" tag:\n" +
" type: string\n" +
" example:\n" +
" id: 1\n" +
" name: Scruffles\n" +
" tag: dog\n" +
" Pets:\n" +
" type: array\n" +
" items:\n" +
" $ref: '#/components/schemas/Pet'\n" +
" Error:\n" +
" type: object\n" +
" required:\n" +
" - code\n" +
" - message\n" +
" properties:\n" +
" code:\n" +
" type: integer\n" +
" format: int32\n" +
" message:\n" +
" type: string\n"
}).then(
function () {
console.log("expectation created");
},
function (error) {
console.log(error);
}
);See REST API for full JSON specification
Calling PUT /mockserver/openapi with a spec you have already imported is safe and idempotent. MockServer performs an incremental sync rather than duplicating expectations:
Incremental sync is scoped by spec identity. MockServer assigns each OpenAPI-generated expectation a stable id of the form openapi:<specKey>:<operationId>, where specKey is derived from the spec title (lowercased, non-alphanumeric characters replaced with _) or, when no title is present, from an 8-character hash of the spec URL or payload. Re-importing a spec with the same title updates exactly those expectations; importing a differently titled spec creates a separate namespace of expectations and does not affect the first.
This means you can safely call PUT /mockserver/openapi on every test run or CI build — you will always end up with a consistent set of mock expectations matching the current spec, with no stale duplicates.
When an OpenAPI specification includes callbacks on an operation, MockServer automatically generates webhook expectations that send HTTP requests to the callback URLs after the main response is returned. This allows you to simulate webhook-style interactions where an API notifies the client asynchronously after processing a request.
The callback URL, method, and request body are derived from the OpenAPI callback definition. OpenAPI runtime expressions (such as {$request.body#/callbackUrl}) are resolved at callback fire-time using values from the triggering request. Supported expressions:
{$request.body#/<json-pointer>} — extracts a value from the triggering request body using a JSON Pointer{$request.query.<name>} — query parameter value from the triggering request{$request.header.<name>} — header value from the triggering request{$request.path.<name>} — path parameter value (best-effort){$request.method} — HTTP method of the triggering request{$url} — reconstructed URL of the triggering requestExpressions that cannot be resolved (unknown format, missing values) are replaced with an empty string. Response-based expressions ({$response.body#/...}) are not currently supported because the response is not available at after-action dispatch time.
For example, given the following OpenAPI specification with a callback:
paths:
/subscribe:
post:
operationId: createSubscription
requestBody:
content:
application/json:
schema:
type: object
properties:
callbackUrl:
type: string
format: uri
responses:
'201':
description: Subscription created
content:
application/json:
schema:
type: object
properties:
id:
type: string
callbacks:
onEvent:
'{$request.body#/callbackUrl}':
post:
requestBody:
content:
application/json:
schema:
type: object
properties:
event:
type: string
subscriptionId:
type: string
responses:
'200':
description: Callback acknowledgedMockServer will create:
POST /subscribe that returns a 201 response with an auto-generated bodyPOST request to the callback URL with an auto-generated request body based on the callback schemaThis feature works automatically when loading OpenAPI specifications via any method (REST API, Java client, initializer file, or classpath). No additional configuration is required.
MockServer supports WSDL 1.1 documents as an alternative to OpenAPI for generating mock expectations. Submitting a WSDL causes MockServer to create one expectation per SOAP operation found across all service/port bindings in the document.
Both SOAP 1.1 and SOAP 1.2 bindings are supported. Each generated expectation:
The WSDL document is parsed with XXE protections (DOCTYPE and external entity resolution disabled) so that importing an untrusted WSDL cannot trigger an XML External Entity attack.
MockServer returns HTTP 201 with the created expectations as JSON.
curl -v -X PUT "http://localhost:1080/mockserver/wsdl" \
-H "content-type: text/xml" \
--data-binary @my-service.wsdlThe request body must be a raw WSDL 1.1 XML document. MockServer returns 201 Created with the generated expectations as JSON.