Mock Responses using OpenAPI metadata

Last updated: Apr 3, 2024 4 minutes read.

The OpenAPI Specification includes metadata that can be used by automatic documentation generators to produce comprehensive reference guides for APIs. Most objects in the specification include a description field that can provide additional human-readable information that is fed into such documentation. Alongside the descriptions, some OpenAPI objects can have sample values listed in the OpenAPI Document that further enhance the generated documentation by giving representative content that the upstream service might provide in responses.

The specification provides two different ways for an API developer to provide sample responses for an endpoint:

example: a sample value that could be returned in a specific field in a response (see below)
examples: a list of key-value pairs comprising of "exampleName":"value" (see below)

Tyk’s mock response middleware can automatically generate a response using the data provided in the OpenAPI description part of the Tyk OAS API Definition.

If neither example nor examples are defined, Tyk can automatically create a mock response if a schema is defined that describes the format of the response as shown below.

Note

Note that example and examples are mutually exclusive within the OpenAPI Document for a field in the responses object: the developer cannot provide both for the same object.
The content-type (e.g. application/json, text/plain) must be declared for each example or examples in the API description.

Using `example` to generate a mock response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


{
  "paths": {
    "/get": {
      "get": {
        "operationId": "getget",
        "responses": {
          "200": {
            "content": {
                "text/plain": {
                    "example": "Furkan"
                }
            },
            "description": ""
          }
        }
      }
    }
  }
}

In this extract from an OpenAPI description, a single example has been declared for a request to GET /get - the API developer indicates that such a call could return HTTP 200 and the body value Furkan in plain text format.

Using `examples` to generate a mock response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


{  
  "paths": {
    "/get": {
      "get": {
        "operationId": "getget",
        "responses": {
          "200": {
            "content": {
              "text/plain": {
                "examples": {
                    "first-example": {
                        "value": "Jeff"
                    },
                    "second-example": {
                        "value": "Laurentiu"
                    }
                }
              }
            },
            "description": ""
          }
        }
      }
    }
  }
}

In this extract, the API developer also indicates that a call to GET /get could return HTTP 200 but here provides two example body values Jeff and Laurentiu, again in plain text format.

The exampleNames for these two values have been configured as first-example and second-example and can be used to invoke the desired response from a mocked endpoint.

Using `schema` to generate a mock response

If there is no example or examples defined for an endpoint, Tyk will try to find a schema for the response. If there is a schema, it will be used to generate a mock response. Tyk can extract values from referenced or nested schema objects when creating the mock response.

Response headers do not have standalone example or examples attributes, however they can have a schema - the Mock Response middleware will include these in the mock response if provided in the OpenAPI description.

The schema properties may have an example field, in which case they will be used to build a mock response. If there is no example value in the schema then default values are used to build a response as follows:

string > "string"
integer > 0
boolean > true

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


{
    "paths": {
        "/get": {
            "get": {
                "operationId": "getget",
                "responses": {
                    "200": {
                        "headers": {
                            "X-Status": {
                                "schema": {
                                    "type": "string",
                                    "example": "Maciej"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "lastName": {
                                            "example": "Petric",
                                            "type": "string"
                                        },
                                        "name": {
                                            "example": "Andrei",
                                            "type": "string"
                                        },
                                        "id": {
                                            "type": "integer"
                                        }
                                    }
                                }
                            }
                        },
                        "description": ""
                    }
                }
            }
        }
    }
}

This partial OpenAPI description defines a schema for the GET /get endpoint that Tyk Gateway could use to generate this mock response:

HTTP/1.1 200 OK
X-Status: Maciej
Content-Type: application/json
 
{
    "lastName": "Petric",
    "name": "Andrei",
    "id": 0
}

Mock Responses using OpenAPI metadata

Using example to generate a mock response

Using examples to generate a mock response

Using schema to generate a mock response

See also

Using `example` to generate a mock response

Using `examples` to generate a mock response

Using `schema` to generate a mock response