有关Swagger 2.0中的XML的问题

Question

我正在使用可以返回XML和JSON的API,并且正在研究是否有任何方法可以在Swagger中表示XML模式,看起来没有.

我有2个跟进问题:

1. 如果我的一个XML返回API在'example'对象中发布了一个XML样本,那么它仍然没问题,对吧？

2. schemas对象具有XML对象.我读了描述,但我不确定这可以用于哪些情况？有人可以举个例子吗？如果可以的话,这真的很有帮助.

我只是想确保我不会遗漏任何我用来使我的API元数据更具描述性的东西.

多谢你们.

Answer 1

当涉及返回XML和JSON的API时,Swagger假设它们共享一个基本上可互换的公共结构.

也就是说,如果你有这个JSON:

{ "key1": "value1", "key2": "value2" }

XML看起来像:

<object>
  <key1>value1</key1>
  <key2>value2</key2>
</object>

如您所见,仍然存在细微差别.XML需要一个包含元素,在JSON中不存在.这是Swagger规范中的XML对象所在的位置,因为它允许您添加此附加信息.它还允许您将字段定义为属性,声明所使用的命名空间并允许更好地控制值数组,这些数组在XML中具有多个变体而不是JSON.

虽然我们没有XML对象的大量示例,但您可以在这里找到一个 - https://github.com/swagger-api/swagger-spec/blob/master/fixtures/v2.0/json/ models/modelWithXmlAttributes.json.我需要在规范中添加更多细节,希望在接下来的几周内.

至于示例字段 - 它的值是一个自由格式的JSON对象.你能做的是这样的:

{
  "xml" : "<object>.....</object>"
}