Question

我已经使用Swagger编辑器（editor.swagger.io）创建了API要求，这些要求在Web浏览器中看起来很不错，但是我想将此Swagger YAML文档转换为可以打印的格式（Word，PDF），Excel，HTML）并离线阅读。

我看到的将Swagger YAML转换为干净的可打印API要求文档的唯一方法是使用Swagger2Markup CLI（这里是参考文档：http://swagger2markup.github.io/swagger2markup/1.3.3/-第8章介绍了CLI），然后进行转换从AsciiDoctor将adoc格式转换为HTML。您可以从Swagger2Markup参考文档中看到最终产品的可读性。

但是，不幸的是，API的最终Swagger2Markup文档没有包含API主体的JSON或xml示例，在我看来，这可以说是文档中最重要的部分！例如，在Swagger编辑器的petstore中，这将是POST / pet API的json正文示例：

{
  "id": 0,
  "category": {
    "id": 0,
    "name": "string"
  },
  "name": "doggie",
  "photoUrls": [
    "string"
  ],
  "tags": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "status": "available"
}

但是这个JSON示例未包含在Swagger2Markup文档中。

所以我的问题是，是否可以更新Swagger2Markup（或更改Swagger2Markup属性）以在最终文档中包含 JSON主体API示例？

如果没有，建议采用其他方法将Swagger YAML转换为包含JSON主体API示例的可读文档吗？

Answer 1

要使用swagger2markup将json主体API示例添加到adoc中，请创建一个配置文件（config.properties）并添加“ swagger2markup.generationExamplesEnabled = TRUE”。根据swagger2markup参考文档第3.2.5节，此属性指定是否应生成http rquest和响应示例。太棒了！

如何在Swagger2Markup API要求中包括JSON主体API示例（从Swagger YAML转换时）？

1 个答案: