如何快速将 swagger 导出 PDF、markdown

Posted 2023-04-02

参考技术A 我们在项目开发完成，接口写好后，需要将接口文档给到前端同学，或者合作方的工程师。但 swagger 对接口阅读并不友好，大部分情况下还得把服务启动好才能访问。这篇文章给各位开发人员介绍如何使用 docway 将 swagger 导出 PDF 或者 markdown 。

1. 打开 swagger ui 的页面

2. 点击 swagger json 的链接（可能没有显示该链接）

3. 如果你的 swagger 页面没有显示该链接，F12打开开发者工具，重新刷新后，复制 api-docs 的响应内容。

4. 在弹出的tab页中或者 api-docs 的内容，复制下来或者保存到本地文件中

1. 登录 http://docway.net

2. 在控制台中，新增项目，选择 导入

3. 选择 swagger 导入，并根据自己的 swagger json 选择是“上传文件方式”还是“粘贴json方式”

4. 导入后，便可以看到项目信息了

1. 在项目的“更多设置”中，找到“项目导出”功能。可以选择 PDF Markdown 导出。

docway 是一款在线接口文档管理工具，除了 PDF markdown 导出， 还支持接口设计、接口分享、接口mock、接口历史记录、接口版本管理、团队管理等功能。

如何以 PDF 和 XML 文件导出 Swagger 文档

【中文标题】如何以 PDF 和 XML 文件导出 Swagger 文档

【英文标题】：How to Export Swagger documentation in PDF and XML files

【发布时间】：2018-04-21 07:21:15

【问题描述】：

我使用以下链接为 web api 生成了招摇文档： http://wmpratt.com/swagger-and-asp-net-web-api-part-1/

需要将文档导出为PDF或XML文件，方便发送。

它的 .NET WEB API。

如何导出swagger文档？

谢谢

【问题讨论】：

Web API Swagger documentation export to PDF的可能重复

【参考方案1】：

您可以使用Swagger2Markup 和AsciiDoc docker 图像：

docker run --rm -v $(pwd):/opt swagger2markup/swagger2markup convert -i "https://api.example.org/api/doc/swagger.json" -f /opt/swagger-doc

在当前文件夹中创建名为“swagger-doc.adoc”的 asciidoc 文件。

docker run -it -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor-pdf swagger-doc.adoc

在当前文件夹中创建一个名为“swagger-doc.pdf”的 PDF 文件。

【讨论】：

仅供参考，此容器不会安装在 Windows 上。

【参考方案2】：

这就是我今天所做的，因为许多其他项目需要费力的变通办法或额外的库或一些完全独立的语言。

转到https://editor.swagger.io/（确保是HTTPS版本） 点击顶部的File => Import File。 选择您的 Swagger JSON 文件。 在顶部，点击Generate Client => HTML2 并下载 ZIP 文件。

这会生成一个静态 HTML 页面，然后您可以使用内置的 Microsoft Print to PDF 打印机、Adobe Acrobat 或您可能想要使用的任何其他工具将其打印（通过浏览器）为 PDF。

【参考方案3】：

Swagger2Markup 项目位于 GitHub 上，您也可以使用 Google 找到更多信息。

Swagger2Markup 将 Swagger JSON 或 YAML 文件转换为多个 AsciiDoc 或 GitHub Flavored Markdown 文档，这些文档可以与手写文档结合使用。

AsciiDoc 比 Markdown 更可取，因为它具有更多功能。 AsciiDoc 是一种文本文档格式，用于编写文档、文章、书籍、电子书、幻灯片、网页和博客。 AsciiDoc 文件可以转换为 HTML、PDF 和 EPUB。 AsciiDoc 比 JavaDoc 或 Annotations 更适合描述公共 API。

您可以通过 asciidoctorj 生成 HTML5、PDF 和 EPUB 文档，甚至可以通过 asciidoctor-gradle-plugin 或 asciidoctor-maven-plugin 生成更好的文档。

该项目至少需要 JDK 8。

另见RESTful API Documentation with Swagger and AsciiDoc

【讨论】：

考虑到特别提到的使用 .NET 的提问者，认为他安装整个 JDK 环境只是为了将 JSON 文件打印到 PDF 是很有趣的！这就像为您的福特买一辆本田去汽车配件店。

【参考方案4】：

他们没有将 swagger 文档导出为 PDF 或任何其他文档的工具或功能。您需要将 swagger.json 文件转换为 yaml 文件，然后您可以将 swagger 作为 html doc 表单 http://editor.swagger.io/。