Allow multiple examples with optional label

Hi, for some routes we need multiple examples for a “Response Object” as well as multiple body payload examples in the “Parameter Object”.

e.g: our API route returns an object with optional properties and we want to show 2 examples how it could look like …

...
{
    ...
    "examples" : [
        {
            "application/json" :
                {
                    "property" : "value"
                }
        },
        {
            "application/json" :
                {
                     "property" : "value",
                     "optional_property" : "value"
                }
        }
    ]
    ...
}

In addition we would like to name/label these examples . In the specification "Example Object"s you can specify different representations of an example for a given MIME-type. I would suggest adding either an optional “name” or “label” property to the “Example Object” which is a string (maybe even an object to allow localized string values for different languages) or to allow custom properties (e.g x-name).

e.g:

...
{
    ...
    "examples" : [
        {
            "application/json" :
              {
                    "property" : "value"
              },
            "name" : "Default Response"
        },
        {
            "application/json" :
                {
                     "property" : "value",
                     "optional_property" : "value"
                },
            "name" : "Response if state of ressource ..."
        }
    ]
    ...
}

If there is any good way to solve it with the current swagger specification, i would love to hear it and it would make this feature request obsolete.

Thanks.

[DavidBiesack]

Addressing @earth2marsh 's earlier comment: x- is not in conflict because like description, x- values would be siblings of value in an Example Object

I agree with @ePaul; this is especially true for APIs which use just application/json their Media Type objects will be complex and can’t split out multiple request/response representations by media types.

Good documentation (which includes good examples - emphasis on plural) is key to successful adoption of APIs. This does not mean the API is designed poorly, it just means it is documented well. Restricting metadata on examples will not lead to better API design. There are plenty of request or response bodies which have mutually-exclusive variation/representation – most notably, when a discriminator is in play.

I don’t consider an object of four fields to be a “beast”. The real issue is: if we do not do this now, we can never do this - we’re shutting a door to future extension that I believe we will regret.

[darrelmiller]

The fact that the OpenAPI spec uses multiple examples to describe many of the features suggests there is value to providing multiple examples. Not being able to explain to describe each of those examples is a significant shortcoming.

One of the primary roles of OpenAPI is to drive documentation. Saying that API documentation can only include one example per request/response body is going to drive people some people to externalize documentation in an ad-hoc way, and cause others to produce less than ideal documentation due to these constraints. I don’t think either outcome is in the best interest of OpenAPI.

I’m not convinced that adding a identifier and a description to an example is over-engineering.