example & default values not exposed in UI

[fehguy]

This PR addresses a lack of support for example values in two scenarios.

First, the defaultValue was lost in the conversion from 1.2 to 2.0.

Next, for 2.0 specs, there is no "place" to put example values for body parameters. To extend the functionality so it's equivalent to 1.2, an extension--x-examples has been added. This allows the mapping of examples which are rendered by the UI.

The current implementation only supports the content-type default. For formal support in upcoming specs, we will likely add content-type so developers can give examples in different formats. See OAI/OpenAPI-Specification#418 for details

[thomas-riccardi]

I assume all this is for parameters only.

First, isn't 1.2 defaultValue the same as 2.0 default ?

Also, I think default is entirely different from examples:

• default: "Declares the value of the item that the server will use if none is provided."
• examples: "An example of the response message."
• example: "A free-form property to include a an example of an instance for this schema."

For parameters, both default and x-example{,s} should be displayed: they are separate values.

This PR merges examples & default values: I think it's not correct.

I'm not sure about examples vs example for parameters: examples require a mimetype, which is only useful for body parameter type. For others the type is already forced, isn't it?

[webron]

@triccardi-systran - in 1.2 we had no examples, so often the defaultValue was used as an example as well. It is true though that defaultValue is the same as default and that default and example are different in terms of purpose. If I'm not mistaken, this PR will use the x-example/x-examples over the default if it exists as the example itself, but the functionality of the default for now remains as it was before as to not break backwards compatibility.

[thomas-riccardi]

Ok, I was not aware of this usage in 1.2.

However this propagates to 2.0 the ambiguity between example and default. It creates real issues, for instance: parameters example still don't exist in 2.0, and if we want to add them, x-example would be a great candidate, but with this PR we cannot anymore (it would be too confusing to have both x-example and x-examples).

What are the benefits of this PR? Why not implement a real example via x-example ? I understand this requires UI modification, so that may be the reason, in which case I think it would be better to not have this PR merged.

[webron]

Not really following the usage of 'real example' here.

[thomas-riccardi]

For me a 'real example' would be an optional additional field for a parameter, listing one (or more) example value for the parameter. It would only be used by swagger-ui complementary to the description of the parameter.

It would be similar to theexamples parameter in the response object, see http://swagger.io/specification/#exampleObject.

Currently we have to manually add examples into the description, this is encouraged by the description documentation: A brief description of the parameter. This could contain examples of use..
However, it doesn't provide a standard way to store examples in the description as would a separate field. This means examples can't be properly displayed & identified as such in a common way across the whole documentation.

[webron]

That's exactly what this ticket aims to solve.

[thomas-riccardi]

As explained in my previous comments, this merged PR doesn't correctly solve the issue because it displays the example value as the default value, which are not the same thing.
We should instead have 2 different displays: one for default, and one for example.

[webron]

Then that's a bug introduced by this PR. Please open a separate ticket for it.