Examples with Valid Request / Response Pairs

Goal:

• Be able to define 1…N vaild request / response pairs as examples.

Use

• This pairs could be used to test the final implementation.
• This pairs could be used to generate easy a some mock for the interfaces.

{
  "paths": {
    "/pets": {
      "get": {
        "summary": "List all pets",
        "operationId": "listPets",
        "parameters": "...",
        "responses": "...",
        "examples": {
          "example_one": {
            "request": {
              "parameters": {
                "limit": 10
              }
            },
            "response": {
              "status": 200,
              "headers": {
                "x-next": 11
              },
              "content": {
                "application/json": {
                  "id": 55226688,
                  "category": {
                    "id": 0,
                    "name": "string"
                  },
                  "name": "doggie",
                  "photoUrls": [
                    "string"
                  ],
                  "tags": [
                    {
                      "id": 0,
                      "name": "string"
                    }
                  ],
                  "status": "available"
                }
              }
            }
          }
        }
      }
    }
  }
}

[ambition-consulting]

I strongly disagree with the answer and the decision to close this request, and find the request still valid:

• Correlating request and response examples is hard requirement for understanding services employing responses with multiple strongly typed response types. Strong typing is a way of letting the compiler help you by providing it with additional information, thus reducing the number of required tests dramatically. Or said differently: A good API doing more than just CRUD resource mappings, will not just return some stupid base class and let the user figure out what it means, but strongly type the different possible return types - which absolutely requires some examples to be better understood.
• Providing instances of a contract does not define the contract, but provides sample data to be used for good testing, documentation etc… That’s why it’s called example, and not schema.
• Reliable testing with external dependencies (such as a REST service specified with OpenAPI) requires Mocks, which are really just request/response pairs. Techniques such as Consumer-Driven-Contract can also make sure, that the Contract is uphold from both sides. A servise will evolve nicely not by letting it’s clients break all the time when something got changed, but by making sure they know about changes automatically and can evolve together with the API.
• Not following this request effectively stops the integration of OpenAPI into automated Unit Testing. And wouldn’t it be nice to not just write down some specification, but also automatically validate that its implementation actually also works?
• Instead, people like myself need to implement all kind of absurd pipelines, just so that we can produce some test data elsewhere to validate our service responses against. And due to the examples specification not getting picked up in time, we even have to duplicate the examples, rendering this great OpenAPI feature less valueable.

[handrews]

Sounds like this was definitively answered in 2018, closing.