Examples with Valid Request / Response Pairs

[chatelao]

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"
                }
              }
            }
          }
        }
      }
    }
  }
}

[MikeRalphson]

Every Media Type Object in OAS v3.0.x supports the examples property. Thus you can embed examples in requestBodies, responses etc. examples is also supported within Parameter Objects.

Could you see if this satisfies your requirement?

[chatelao]

I know - But my question is: how can i define a consistent [All Requests - All Responses] set?

[MikeRalphson]

I'm not sure what you mean by either "consistent" or "all". Could you expand a little?

[darrelmiller]

@chatelao Correlating response bodies with request bodies within a single operation is a design smell. It encourages coupling between client and server based on out-of-band knowledge, which reduces the evolvability of a service. Responses should be self-descriptive. You shouldn't need to know what the request was to understand what the response means. The request should describe the intent of the client. Defining a contract that says exactly how a server must respond to a client's specific request is highly problematic. I know many people want to do it. I generally try and discourage people from doing it because that's not HTTP is supposed to work.

[handrews]

Sounds like this was definitively answered in 2018, closing.

[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.