如何将 Swagger 文档导出为 PDF 文件

在 Web 开发领域，创建和共享全面的 API 文档至关重要。 Swagger，或者说 OpenAPI Specification （OpenAPI 规范），是一种广泛使用的工具，用于定义和记录 RESTful API 。

然而，你会发现自己可能需要将 Swagger 文档导出为 PDF 或文件，以便于共享和存档。在这篇博文中，我们将指导你完成以不同方式将 Swagger 文档导出为 PDF 格式的过程。

导出 Swagger 文档的重要性

为什么将 Swagger 文档 导出为 PDF 格式至关重要？你提到你一直在使用 Swagger UI 来展示托管在服务器上的 REST Web 服务。

然而，访问 Swagger UI 需要互联网连接和对特定服务器的访问权限。为了离线工作，并与可能无法访问服务器的其他人共享文档，将 Swagger 文档导出为 PDF 格式可能是一个很好的解决方案。

以下是将 Swagger 文档转换为 PDF 格式的一些主要好处：

1. 离线可访问性： 通过 PDF，即使你未连接到互联网或托管 Swagger UI 的服务器，也可以访问和引用你的 API 文档。
2. 易于共享： PDF 具有广泛的兼容性，可以轻松地与团队成员、客户或任何需要了解你的 API 功能的人共享，而无需他们访问服务器。
3. 存档目的： PDF 文件适用于长期存档，确保你的 API 文档得到保存，并且可以在将来引用，即使托管的 Swagger UI 不再可用。
4. 灵活性： 一些用户可能更喜欢使用 PDF 格式，特别是当他们需要注释、突出显示或打印文档时。同时提供 Swagger UI 和 PDF 版本可以满足不同的用户偏好。

如何将 Swagger 文档导出为 PDF

将 Swagger 文档导出为 PDF 文件是一个相对简单的过程。让我们分步骤地用几种方式来分解它。

1. 使用 Swagger to PDF 在线工具

如果你想找到一种从 Swagger API 文档生成 PDF 文件的简单方法，在线工具非常适合你。

Swagger to Pdf 是一个很棒的在线工具，位于 swdoc.org，它使用你提供的 swagger.json 规范，以简洁的 PDF 形式创建 API 文档。它利用了 Swagger2Markup 转换器和强大的 AsciiDoctor 。

该方法与之前的解决方案类似。首先， Swagger2Markup 获取你的 swagger.json 文件，并将其转换为 AsciiDoc 文件。然后，强大的 AsciiDoctor 解析这些文件，构建一个文档模型，然后再将其雕刻成一个漂亮的 PDF 。

有两种方法可以使用 Swagger to Pdf，一种是使用 URL 生成，另一种是使用 JSON 。

现在，我们将详细向你展示第一种方法。首先，你需要准备 API 文档并复制 URL，然后将其粘贴到 Swagger to PDF 在线工具中。只需单击 "Generate" 按钮。

完成该过程后，你可以单击 "Download" 以保存 PDF Swagger 文档。

2. 将 Swagger 文档转换为 PDF 格式

如果你只想在 Swagger 中完成整个过程，这里有一种传统的方法供你参考。

步骤 1：访问 Swagger Editor

首先，在 Web 浏览器中打开 Swagger Editor 或 Swagger Hub 。如果你没有准备好 Swagger 文档，你可以创建一个或导入一个现有的规范。

步骤 2：审查和验证

在导出之前，彻底审查你的 Swagger 文档，以确保准确性、完整性和正确的格式。使用内置的验证工具来捕获和纠正任何潜在的错误。

步骤 3：将 OpenAPI 文档导出为 ZIP 文件

在上半部分，选择 "Generate Client"，然后选择 "HTML2"，这将允许你下载 ZIP 文件。

然后， Swagger Editor 将生成一个包含你的 API 文档的 ZIP 文件。

步骤 4：转换 PDF 并从 PDF 打印

此文件是一个静态 HTML 页面，可以通过你的 Web 浏览器进一步转换为 PDF 格式，利用集成的 Microsoft Print to PDF 打印机、 Adobe Acrobat 或你选择的任何其他工具。你可以选择直接与你的团队和客户共享它，或者存储它以供将来参考。

Apifox：支持以不同的格式导出 API 文档

Apifox 在为你的 API 文档提供灵活性方面表现出色，它提供各种导出格式，交互式 HTML 页面、静态 HTML 页面、 Markdown 、 Swagger 和纯文本。

这种广泛的格式范围确保你的 API 文档能够满足你的目标受众的不同偏好和要求，从而更好地理解和利用你的 API 。借助 Apifox，你可以轻松地获得 API 文档的多功能性，从而确保你的文档能够满足具有不同偏好的开发人员和团队的需求。

结论

将 Swagger 文档导出为 PDF 格式可以增强你的 API 文档的可访问性、可共享性和存档功能。无论你管理的是小型项目还是大型组织的庞大 API ，以这些格式提供文档都能确保开发人员和利益相关者能够有效地访问和使用这些信息。

通过遵循本博文中概述的简单步骤，你可以轻松地将 Swagger 文档导出为 PDF 文件。这些格式提供多功能性和兼容性，使其成为开发人员和组织有价值的资源。因此，下次你需要共享或存档你的 API 文档时，请考虑以 PDF 格式提供它的优势，并使用 Swagger 来简化此过程。