Using OpenAPI Specifications

MockServer supports OpenAPI v3.0 specifications in either JSON or YAML format.

Note: MockServer uses the swagger-parser library, which targets OpenAPI 3.0.x and has partial support for OpenAPI 3.1. Most 3.1 specifications load, but some 3.1-only constructs (such as $ref siblings, type as an array, and the webhooks top-level key) may not be fully handled. If you hit validation or parsing issues, try converting your specification to OpenAPI 3.0.x.

OpenAPI specifications can be used in request matchers for

expectation request matchers
verifying requests and verifying request sequences
clearing logs
retrieving logs, recorded requests and expectations

OpenAPI specifications can also be used to generate expectations with example responses.

Generate Expectations From OpenAPI

MockServer supports open api expectations containing the follow fields:

specUrlOrPayload - mandatory value containing an OpenAPI v3 specifications in either JSON or YAML format as an:
- HTTP/HTTPS URL
- File URL
- classpath location (without the classpath: scheme)
- inline JSON object
- inline escaped YAML string
operationsAndResponses
- optional value that specifies which specifies operations are included, if not specified all operations are included
- specified which response body when multiple response bodies are specified (i.e. different status codes), if not specified the first response body is used
- fields names are operationId indicating the operation in the OpenAPI specification
- field values are a string statusCode (such as "200", "400" or "default") indicating the response body for the specified operation

For each open api expectations MockServer creates multiple request matcher expectations as follows:

request matcher
- each expectation will use an open api request matcher to match requests.
action
- a response action is added to each expectation using examples provided in the specification
- if no examples are provided in the specification then the response is auto-generated from schema definitions for response body and headers of the operation
- if multiple response bodies are specified for an operation (i.e. different status codes) the first response body is used by default, however this can be controlled by using operationsAndResponses

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);
    }
);