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

OpenAPI specifications can be used in request matchers for

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:
  • 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
  • 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/master/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/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
  }
}
{
  "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": "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/master/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/master/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/master/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/master/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/master/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/master/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