使用Swagger API文档生成PDF

Question

我使用Swagger UI来展示我的REST web服务，并将其托管在服务器上。

但是这个Swagger服务只能在特定的服务器上访问。如果我想离线工作，有人知道如何使用Swagger UI创建静态PDF并与之交互吗？此外，PDF易于与没有访问服务器权限的人共享。

非常感谢！

- Aman Mohammed

Answer 1

方便易行的方法：使用浏览器打印/预览

1. 隐藏编辑窗格
2. 打开打印预览（我用的是火狐浏览器，其他浏览器也可以）
3. 更改页面设置并打印成 PDF 格式

- Osify

---

简单！文档输出得非常好。 - ShaTin

你甚至可以在两个Swagger服务中选择两种不同的文档设计：https://editor.swagger.io/（新版）和http://editor2.swagger.io（旧版）！ - naXa stands with Ukraine

有效但有损失，因为Swagger HTML UI具有多个选项卡，对于POST/PUT方法的参数，您必须在模型选项卡和示例值选项卡之间进行选择，然后在打印为PDF版本时，其中一个选项将永远隐藏 :( - chrisinmtown

这对我没有用。每个端点都会在页面末尾被截断（无论我使用什么页面设置）。下一页将从下一个端点块的顶部开始。也许自回答以来有些变化。 - Synctrex

我仍然认为这是可行的，你可能需要调整边距。请从https://editor.swagger.io/尝试。 - Osify

Answer 2

我找到了一种方法，使用https://github.com/springfox/springfox和https://github.com/RobWin/swagger2markup

使用Swagger 2来实现文档化。

- Aman Mohammed

---

你好，我也在尝试使用Swagger生成离线文档。你能够生成Swagger文档吗？ - Sunil Rk

是的，我使用了示例项目并将我的 Web 服务代码集成到其中，并成功生成了文档。 - Aman Mohammed

请简要告诉我，如何将我的 Web 服务集成到您上面提到的示例中。 - Sunil Rk

swagger2markup项目需要REST API的JSON输入。如果您下载该gradle项目并将其中的swagger.json文件更改为您的API详细信息，然后运行Swagger2MarkupConverterTest JUnit方法：testSwagger2HtmlConversion，它应该在项目的build/docs/generated/asciidocAsString文件夹中为您生成HTML。换句话说，有两件事情。1）首先使用Swagger Editor生成REST API的JSON格式。2）使用该JSON格式，您可以使用swagger2markup项目生成API的独立HTML文档。 - Aman Mohammed

Answer 3

我创建了一个网站 https://www.swdoc.org/，专门解决这个问题。所以它会自动将swagger.json -> Asciidoc, Asciidoc -> pdf转换成答案中建议的形式。这样的好处是您不需要经过安装程序的步骤。它接受一个url格式或原始json格式的规范文档。该项目使用C#编写，其页面为https://github.com/Irdis/SwDoc。

编辑

如果您在使用SwDoc时遇到任何问题（例如生成的pdf不完整），可以在此处验证您的json规范：http://editor.swagger.io/，这可能是一个不错的主意。

- Irdis

---

谢谢，是的，它相当不错，我用它来做我的工作项目。我正在考虑利用空余时间编写一些代码以支持openapi 3.0。 - Irdis

所有荣耀归功于它所依赖的工具的作者，当然。 - Irdis

@Irdis 我尝试使用该链接。它可以解析Swagger 2.0文档，但我提供的文档是Open API 3.0，无法生成文档。 - hellowahab

我尝试了Swagger 3+ - 运行良好，但是它显示注释的原始HTML... - Sasha Bond

这是一个很棒的工具！如果你遇到像我一样的问题（例如生成的pdf不完整），请将你的json粘贴在这里：http://editor.swagger.io/ 进行自动验证、修复问题，然后你就可以回到swdoc工具中重新生成了。 - Thales Valias

你应该添加自动检测3.0规范。 - dataman

Answer 4

对我来说，最简单的解决方案是将Swagger（v2）导入Postman，然后转到Web视图。在那里，您可以选择“单列”视图，并使用浏览器打印为PDF。虽然不是自动化/集成解决方案，但适用于单次使用。它比从editor2.swagger.io打印要好处理纸张宽度，因为滚动条会导致内容的某些部分被隐藏。

- Simon

---

尝试使用这个，但是通过网页打印会添加几个链接和其他信息。 - hellowahab

是的，我应该提到。对我的使用来说不是问题。 - Simon

Answer 5

我正在寻找一个相对快速简单的东西，最小化软件安装。我在寻找可以粘贴到Word文档中以显示API已经存在的东西；我不需要任何交互级别或复制粘贴操作能力。

我已经有一个名为PicPick的软件，它是一个截屏工具，可以捕获滚动窗口（它可以滚动，截图并拼接在一起生成一个非常高的图像）

它也可以保存为PDF，但大小不好，所以我通过Publisher进行了处理。

• 运行我的启用了Swagger的NetCore API项目
• 浏览器出现了Swagger生成的“试一下”页面，这对于目的来说已经足够好了
• 隐藏试用按钮：右键单击“试一下”>>“检查元素”>>添加CSS类>>display: none以隐藏试用
• PicPick托盘图标>>捕获>>滚动窗口
• 单击浏览器的内容窗格
• 注意：PP可能只能在光标悬停在窗口上时滚动窗口-至少我是这样发现的
• 等待一段时间，它会重复滚动、截屏并将图像拼接在一起
• 将结果保存为PNG格式
• 加载Publisher，设置自定义页面大小（PNG尺寸除以96）英寸
• 插入图像并重置为100%大小
• 另存为PDF格式

- Caius Jard