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

Posted 2023-02-18

【中文标题】如何以 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/。