Problems with x-examples and x-example vendor extension support

[andylowry]

In the swagger-models project:

The BodyParamter class has special code to de/serialize an x-examples property. My understanding of the history of this suggests that it's supposed to put request and response payloads on a more equal footing models, making up for an oversight in the original Swagger design.

However, while the examples property in a response maps content-type strings to arbitrary JSON values (the field in the Response class is of type Map<String,Object>), the examples in body params must be strings (the field in BodyParameter class is Map<String,String>).

This means, for example, that one cannot use a YAML editor to conveniently construct body parameter examples - as one can with responses - since a YAML object is not valid. One can construct the value as a YAML object, but then it must be turned into a block literal string, e.g. by changing : into : |. Objects are accepted by some other swagger.io offerings.

In a related - but IMO less serious issue, the code in AbstractSerializableParameter that handles x-example values lets in arbitrary objects when it probably should not. Here, it seems the value should be constrained according to the primitive parameter type. To what extent that happens depends on the primitive type:

• Strings - not at all
• Integer types - A conversion is attempted, and if it fails a warning is issued
• Float types - like integers
• Boolean - a conversion is attempted, but there's no warning on failure

In all cases, an inappropriate value is retained, so I could stick a complex object on a primitive parameter as an example value if I wanted to.

Incidentally, the warning message issued for conversion failures on integer/float types talks about an invalid "default" value, not an "example." Looks like a cut/paste error.

[fehguy]

@andylowry we actually are about to refactor the examples for the 3.0 spec support. Admittedly they are not great in the current code but any changes will definitely break the signatures, and right before the 3.0 spec hits RC-0 (next week). So my suggestion is hold on changing the examples in the 1.5.x swagger-core and submodules, and focus on a plan for 3.0.

On that front, I'm expecting to port some of this code:

https://github.com/swagger-api/swagger-inflector/tree/master/src/main/java/io/swagger/inflector/examples

into swagger-core, support proper example objects, etc. Take a look and share your feedback if you're interested.