Skip to main content
MockServer has first-class support for OpenAPI v3 specifications. You can use a spec in two ways:
  1. Generate expectations — MockServer reads each operation in the spec and automatically creates a matching expectation with an auto-generated example response.
  2. Match requests — Use the spec as a request matcher inside an expectation so that only requests conforming to a specific operation are matched.

​
Generate expectations from an OpenAPI spec

Submit a spec to MockServer using the /mockserver/openapi endpoint. MockServer creates one expectation per operation, with a response action derived from the operation’s example or schema definitions.

​
Load from a URL

new MockServerClient("localhost", 1080)
    .upsert(
        openAPIExpectation(
            "https://raw.githubusercontent.com/mock-server/mockserver/master/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json"
        )
    );

​
Load from a file path

curl -v -X PUT "http://localhost:1080/mockserver/openapi" -d '{
    "specUrlOrPayload": "file:/Users/jamesbloom/git/mockserver/openapi_petstore_example.json"
}'

​
Load from a classpath location

curl -v -X PUT "http://localhost:1080/mockserver/openapi" -d '{
    "specUrlOrPayload": "org/mockserver/openapi/openapi_petstore_example.json"
}'
Do not include the classpath: scheme prefix — just provide the path relative to the classpath root.

​
Load from an inline JSON object

Pass the spec content directly in the request body. In the REST API, embed the spec JSON as the value of specUrlOrPayload: 
curl -v -X PUT "http://localhost:1080/mockserver/openapi" -d "{
    \"specUrlOrPayload\": $(cat /path/to/openapi_petstore_example.json)
}"
In JavaScript, read the file and pass the string: 
var fs = require('fs');
var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).openAPIExpectation({
    "specUrlOrPayload": fs.readFileSync("/path/to/openapi_petstore_example.json", "utf8")
});

​
Load from an inline YAML string

Pass the YAML spec as a string value for specUrlOrPayload: 
new MockServerClient("localhost", 1080)
    .upsert(
        openAPIExpectation(
            "---\n" +
            "openapi: 3.0.0\n" +
            "info:\n" +
            "  version: 1.0.0\n" +
            "  title: Swagger Petstore\n" +
            "paths:\n" +
            "  /pets:\n" +
            "    get:\n" +
            "      summary: List all pets\n" +
            "      operationId: listPets\n" +
            "      responses:\n" +
            "        '200':\n" +
            "          description: A paged array of pets\n"
        )
    );

​
Filtering operations and selecting response codes

Use operationsAndResponses to control which operations generate expectations and which status code is used for each operation’s response. Keys are operationId values from the spec; values are status code strings ("200", "400", "default", etc.). 
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/master/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json",
            operationsAndResponses
        )
    );
When you submit the above, MockServer creates one expectation per listed operation: 
{
  "priority": 0,
  "httpRequest": {
    "specUrlOrPayload": "https://raw.githubusercontent.com/mock-server/mockserver/master/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 }
}
If operationsAndResponses is omitted, all operations are included and the first response body defined for each operation is used.

​
Use an OpenAPI spec as a request matcher

Instead of generating expectations, you can use a spec as the request matcher inside a regular expectation. This lets you route all requests that match a given operation to a custom response action. 
// match all operations in the spec
new MockServerClient("localhost", 1080)
    .when(
        openAPI(
            "https://raw.githubusercontent.com/mock-server/mockserver/master/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json"
        )
    )
    .respond(
        response().withBody("some_response_body")
    );

// match a specific operation
new MockServerClient("localhost", 1080)
    .when(
        openAPI(
            "https://raw.githubusercontent.com/mock-server/mockserver/master/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json",
            "showPetById"
        )
    )
    .respond(
        response().withBody("some_response_body")
    );
When operationId is omitted, any request matching any operation in the spec will trigger the expectation.
When you use an OpenAPI spec as a request matcher, MockServer internally converts it to a set of request properties matchers. This means operations such as clearing expectations and retrieving active expectations work consistently regardless of whether a request properties matcher or an OpenAPI matcher was used.

​
Match exactly N times using OpenAPI

Combine an OpenAPI request matcher with times to limit how often the expectation fires: 
curl -v -X PUT "http://localhost:1080/mockserver/expectation" -d '{
    "httpRequest": {
        "specUrlOrPayload": "https://raw.githubusercontent.com/mock-server/mockserver/master/mockserver-integration-testing/src/main/resources/org/mockserver/openapi/openapi_petstore_example.json",
        "operationId": "showPetById"
    },
    "httpResponse": {
        "statusCode": 200,
        "body": "some_body"
    },
    "times": {
        "remainingTimes": 2
    }
}'