Ability to specify more complete examples in a specification

[meastp]

I haven't thought a lot about this, but I'm writing a specification with a lot of examples (requests, responses)

• I miss a way to specify parameters used to get a particular response.
• I miss a way to combine multiple sequential examples to illustrate usage of the API. This could perhaps also be used to generate unit tests..?

[Simran-B]

We also miss this ability. Some of our APIs can only be demonstrated in a meaningful way if a combination of path parameters, query parameters, HTTP headers and a JSON payload (with certain attributes and values) is used.

On top of that, it would be super valuable to be able to validate the examples against an actual server as integration/regression test for the documentation.

Here is Microsoft's take on this:

• https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/x-ms-examples.md
• https://github.com/Azure/autorest/blob/master/packages/libs/autorest-schemas/example-schema.json

[lornajane]

I think this is about not just examples, but which example goes with which other context. #2610 covers similar ground and while I am not sure how we would do this within a specification format, it is a real use case IMO.

[Simran-B]

I believe OpenAPI Workflows cover this use case but as far as I understand, a workflow description would live in a separate file to the OpenAPI specification:
https://github.com/OAI/sig-workflows/blob/main/versions/1.0.0.md

[handrews]

The two requests are being tracked or addressed in:

• [Request] Define parameters in Example Object #2610
• Extend V3 "examples" spec to include names (or IDs) and more data #1265
• Proposal: Having an example for an entire operation in one place (request + response) #859
• OAI/Arazzo-Specification (formerly known as Workflows)

I'm closing this issue in favor of those.