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

Question

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

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

它的 .NET WEB API。

如何导出swagger文档？

谢谢

Answer 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 文件。

Answer 2

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

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

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

Answer 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

Answer 4

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