对于一些用 PHP 编写的 REST API，我被要求创建 Swagger 文档，由于我不知道有任何简单的方法可以向这些现有 API 添加注释并创建这样的文档，所以我使用了 this editor暂时生成一些。
我保存了使用该编辑器创建的 JSON 和 YAML 文件，现在我需要创建最终的交互式 Swagger 文档（这种说法可能听起来幼稚和含糊）。
有人可以告诉我如何将 Swagger JSON 规范文件转换为实际的 Swagger 文档吗？
我在Windows平台，对Ant/Maven一无所知。
【问题讨论】：
标签： yaml swagger swagger-php
尝试使用 redoc-cli。
我使用bootprint-openapi 生成一堆文件（bundle.js、bundle.js.map、index.html、main.css 和main.css.map），然后您可以将其转换为单个@987654329 @file 使用html-inline 生成一个简单的index.html 文件。
然后我发现redoc-cli 非常好用，输出非常棒，单一而漂亮的 index.html 文件。
安装：
npm install -g redoc-cli
用法：
redoc-cli bundle -o index.html swagger.json
【讨论】：
npx redoc-cli ... 执行更可靠。
当我在寻找一个工具来做到这一点时，我对swagger-codegen 不满意，所以我自己写了一个。看看bootprint-swagger
与swagger-codegen 相比，主要目标是提供简单的设置（尽管您需要nodejs）。
并且应该很容易根据自己的需要调整样式和模板，这是bootprint-project 的核心功能
【讨论】：
spectacle 从 swagger JSON 中生成了更好看的文档
一切都太难或记录不充分，所以我用一个简单的脚本 swagger-yaml-to-html.py 解决了这个问题，就像这样
python swagger-yaml-to-html.py < /path/to/api.yaml > doc.html
这适用于 YAML，但修改它以使用 JSON 也很简单。
【讨论】：
有
我正在查看 Swagger Editor，并认为它可以导出预览窗格，但结果却不能。所以我写了我自己的版本。
完全披露：我是该工具的作者。
【讨论】：
allOf 都会产生undefined，即使在最简单的情况下（“合并”单个对象，相当于根本不使用allOf）。
allOf 功能。看看吧。
我花了很多时间，尝试了很多不同的解决方案——最后我是这样做的：
<html>
<head>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3.17.0/swagger-ui.css">
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<script>
function render() {
var ui = SwaggerUIBundle({
url: `path/to/my/swagger.yaml`,
dom_id: '#swagger-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
]
});
}
</script>
</head>
<body onload="render()">
<div id="swagger-ui"></div>
</body>
</html>
您只需要从同一位置提供 path/to/my/swagger.yaml。
（或使用 CORS 标头）
【讨论】：
参见 GitHub 上的 swagger-api/swagger-codegen 项目；项目 README 展示了如何使用它来生成静态 HTML。见Generating static html api documentation。
如果您想查看 swagger.json，您可以install the Swagger UI 并运行它。您只需将其部署在 Web 服务器上（从 GitHub 克隆存储库后的 dist 文件夹）并在浏览器中查看 Swagger UI。这是一个 JavaScript 应用程序。
【讨论】：
你也可以从https://github.com/swagger-api/swagger-ui下载swagger ui， 取 dist 文件夹，修改 index.html： 改变构造函数
const ui = SwaggerUIBundle({
url: ...,
进入
const ui = SwaggerUIBundle({
spec: YOUR_JSON,
现在 dist 文件夹包含您需要的所有内容，并且可以按原样分发
【讨论】：
对于 Swagger API 3.0，从在线 Swagger 编辑器生成 Html2 客户端代码非常适合我！
【讨论】：
看看这个链接：http://zircote.com/swagger-php/installation.html
如果您需要其他帮助，请随时提出。
【讨论】：
有一个小的 Java program 从 yaml 文件生成文档（adoc 或 md）。
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withSwaggerMarkupLanguage(MarkupLanguage.ASCIIDOC)
.withOutputLanguage(Language.DE)
.build();
Swagger2MarkupConverter builder = Swagger2MarkupConverter.from(yamlFileAsString).withConfig(config).build();
return builder.toFileWithoutExtension(outFile);
很遗憾，它只支持OpenAPI 2.0，不支持OpenAPI 3.0。
【讨论】：
如果你在 Gitlab 中提交你的 JSON 文件，它会为你呈现它。
【讨论】：