Provide XML examples as well as JSON

[jugglingcats]

Apologies if this is a duplicate, I couldn't find it in open issues and very little in other forums.

It would be very nice if Swagger UI could generate XML examples (input and response) for services that produce or consume XML.

It might be possible to implement (relatively) easily by adding conversion methods to ApiListingResource. It could use Jackson to convert from the JSON example to POJO then use JAXB to produce the XML representation, to return to Swagger UI. I guess this would mean changing swagger-jersey-jaxrs, but cannot see how it could be done purely client side. Unfortunately I don't do Scala well, so can't have a go at it...!

Thanks.

[webron]

I believe that when using Swagger 1.2 and prior to it, implementing it would be a bit of an issue since the json-to-xml translation isn't always clear. Just to give you an idea, assume an array of strings.

In JSON, it would look like this:

{
  [ "hello", "world" ]
}

In XML it could look like this:

<object>
  <items>
    <item>"hello"</item>
    <item>"world"</item>
  <items>
</object>

Or this:

<object>
  <item>"hello"</item>
  <item>"world"</item>
</object>

Or even this:

<object>
  <items>
    <item value="hello"/>
    <item value="world"/>
  <items>
</object>

The right way to describe it is based on how the server expects to receive it, but we cannot imply the proper structure with the specification itself, so producing such examples automatically simply won't work.

However, with the new Swagger Specification 2.0, we've introduced a better way to define and control such conversions, and for that we may be able to implement the support you request in the future.

[jugglingcats]

Thanks for the reply. I realise now that you need Swagger UI to work purely off the spec info. I am using it in conjunction with the Jersey integation server-side to dynamically generate the spec. Of course the JAXB annotations indicate exactly how the XML should be formed, and so I thought it might be possible for Swagger UI to invoke this feature dynamically (purely for examples)... but I guess it is not the right approach, especially as better support is in the 2.0 spec. I guess it will take a while for the tools and Swagger UI to catch up though.

[webron]

You can use both swagger-core 1.5.0-SNAPSHOT and the swagger-ui's master version for Swagger 2.0 support. Those are still under development so there may be bugs, but if you feel adventurous and want to help us test it out, you're more than welcome.

[fehguy]

depends on #1248

[fehguy]

Please track meta issue #1248