api - 关于 Swagger 2.0 中 XML 的问题

Question

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

我有 2 个跟进问题:

1. 如果我的 XML 返回 API 之一在“示例”对象中发布了 XML 样本，那也没问题，对吧？

2. 模式对象有一个 XML 对象。我阅读了描述，但我不确定这可以用于哪些情况？谁能举个例子吗？如果可以的话，这真的很有帮助。

我只是想确保我没有遗漏任何可以用来使我的 API 元数据更具描述性的东西。

谢谢你们。

Answer 1

当谈到同时返回 XML 和 JSON 的 API 时，Swagger 假定它们共享一个基本上可以互换的通用结构。

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

{
“键1”:“值1”，
“键2”:“值2”
}


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>"
}