Questions about XML in Swagger 2.0 - api

Question

I'm working with APIs that could return XML as well as JSON, and was looking into if there's any way to represent XML schemas in Swagger and looks like there is none.
I had 2 follow up questions:
If one of my XML returning API's posts an XML sample in the 'example' object, that's still fine, right?
The schemas object has a XML Object. I read the description but I'm not sure what cases can this be used for? Could anyone please give an example? It'd be really helpful if you could.
I just want to make sure I'm not leaving out anything that I could have used to make my API metadata more descriptive.
Thanks guys.

Answer 1

When it comes to APIs returning both XMLs and JSON, Swagger assumes that they share a common structure that's basically interchangeable.
That is, if you have this JSON:
{
"key1": "value1",
"key2": "value2"
}
The XML would look like:
<object>
<key1>value1</key1>
<key2>value2</key2>
</object>
As you can see, there are still slight differences. The XML needs an encompassing element, which does not exist in JSON. This is where the XML Object in the Swagger Spec comes in as it allows you to add this additional information. It also allows you to define a field as an attribute, declare the namespace used and allow better control for arrays of values, which have several variants in XML as opposed to JSON.
While we don't have a wide array of samples for the XML Object, you can find one here - https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/models/modelWithXmlAttributes.json. I need to add some more details to it in the spec, hopefully in the upcoming few weeks.
As for the example field - its value is a free-form JSON object. What you can do is something like this:
{
"xml" : "<object>.....</object>"
}

Answer 2

See swagger results below.
{
"in": "body",
"name": "xmlbody",
"description": "example of swagger with xml",
"required": true,
"schema": {
"$ref": "#/definitions/myOuter"
}
}
definitions:{
"myOuter":{
"type":"object",
"xml":{
"name":"House"
},
"properties":{
"class":{
"type":"string",
"enum":[
"singleFamily"
],
"xml":{
"attribute":true,
"prefix":"home"
}
},
"masterRoom":{
"type":"object",
"properties":{
"bed":{
"type":"string",
"xml":{
"prefix":"master"
}
},
"size":{
"type":"string",
"enum":[
"XL"
],
"xml":{
"attribute":true
}
},
"color":{
"type":"string",
"enum":[
"brown"
],
"xml":{
"attribute":true,
"name":"COLOR",
"prefix":"paint"
}
},
"window":{
"type":"string",
"enum":[
"slide"
],
"xml":{
"attribute":true,
"name":"open",
"prefix":"view",
"namespace":"http://doesntShowUpDueToENUM.com"
}
}
}
}
}
}
}
<?xml version="1.0"?>
<House home:class="singleFamily">
<masterRoom size="XL" paint:COLOR="brown" view:open="slide">
<master:bed>string</master:bed>
</masterRoom>
</House>