Allow multiple examples with optional label

[elmolicious]

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.

[mkrufky]

+1 I also have an endpoint that can be used in different ways. The required and optional argument fields can vary depending on the function being carried out. It would be great to be able to represent the same endpoint multiple times, specifying different arguments (and response body), rather than having to represent it all at once, marking all arguments as optional

[arno-di-loreto]

+1 having a description in addition to the name would be great too
All this could like like this maybe:

examples:
  - name: An first example
    description: use case
    content:
      - application/json : <example for media type application/json>
      - application/xml: <example for media type application/xml>

That could be useful for documentation but I think also for mock API generation

[arno-di-loreto]

Based on how Example Object are defined and used in version 3.0.0-rc0, I think that the it could be slightly modified to provide documentation data this way:

Current Example Object is a freeform object, array or primitive value.

Modified Example Object is an Object with these properties:

• summary (String) : An optional short description or name
• description: (String): An optional longer description
• data (free form object, e.g. what is the current Example Object (I have not found a better name)

Having documented examples, or at least named examples is definitely a must have when documenting an API, especially if you provide various examples: how the readers would know what is the difference between these examples.

@webron or @darrelmiller what do you think about this?

[DavidBiesack]

1+, but rather than "just free form object", we should not imply that a JSON object is required; an Example could be a array or even a primitive value. (I htink Example Object is currently named incorrectly since it is not always an Object, but if we adopt your suggestion, the name would be correct.)

I suggest value instead of data.

[darrelmiller]

I wonder if we can kill two birds with one stone here. There has been a question about the redundancy of having example and examples #953. Perhaps we can leave example as the freeform simple scenario with no metadata and have the examples be an array of objects as @arno-di-loreto has described them. The need for a description only really arises when there are multiple examples. I also like the idea of having summary and description properties.

[arno-di-loreto]

So we could have something like that:

• example : Example Object is a freeform object, array or primitive value (or something else as suggested by @DavidBiesack)
• examples: Array of "Documented Example Object" (naming thing is definitely hard), which is an Object with these properties:
  • summary (String) : An optional short description or name
  • description: (String): An optional longer description
  • value (Example Object): the documented example with a better name thanks to David!

I really like that!

[arno-di-loreto]

I'm wondering if the summary property shouldn't be required?

[DavidBiesack]

summary is not required in other places, even where it is a "good idea". I don't think it should be required here.

[DavidBiesack]

If we keep example, let's not call it Example Object, just Example or Example Value; and for the array use [ Example Object ]; .value is an Example (or Example Value)

[darrelmiller]

Although I am a fan of this idea, be warned that getting any new features into the spec at this point does not have a high probability of success.

[DavidBiesack]

I say we try to increase the probability of success 😁

[arno-di-loreto]

Can we bribe some people? 😋

In current state the examples property may not be usable IMHO especially for documentation, mocking and testing tooling.

• Having something to understand what an example in a list of examples is a must have for human beings.
• Having something to identify an example (using summary or maybe a new id property) can also help to connect example in parameters/request bodies/responses, this is a must have for documentation, mocking and testing tooling.

And postponing this modification that billions of people will ask for will lead to a breaking change later 😁

[DavidBiesack]

an Examples Object should also allow x- extensions

[ePaul]

Looks like everyone here thinks this is a good idea (though the only one from the @OAI/tdc who said something was @darrelmiller, so it might not be representative for the decision makers) ... who wants to write it up into a pull request?

[darrelmiller]

Just one other item that was just brought to my attention. With examples as an array and summary/description as optional fields it becomes possible to define multiple examples with no way of identifying or referencing one example vs another. That could make life difficult for tooling. We have a couple of options. We could introduce a name property as was suggested earlier by @arno-di-loreto or the array could be a map and the key becomes the identifier.