Swagger API：工作原理与关键要点

您或您的开发团队已经决定采用RESTful API，以充分利用 REST 框架的灵活性、速度和效率。然而，SOAP 是一种带有规范设计的协议，而 REST 是一种架构，因此需要一个规范来定义如何处理数据。OpenAPI 规范（以前称为 Swagger 规范）就是这样的解决方案之一，但是什么是 Swagger，它是如何工作的，它又如何帮助您创建高质量的 API 文档呢？

什么是 Swagger？

让我们首先纠正一些术语。由于 OpenAPI 规范最初被称为SwaggerAPI，所以有时人们仍然将 OpenAPI 规范称为 Swagger。在本文中，当我们提到 Swagger 时，我们指的是为帮助设计、构建和记录使用 OpenAPI 规范的 API 而生产的一套工具。

用于 API 文档的 Swagger 工具

除了“专业”工具（基于订阅）之外，Swagger 还提供了一套流行的开源工具，用于 API 开发和文档记录，包括：

Swagger Editor

Swagger Editor 主要是开发人员设计和构建其 RESTful API 的工具，同时根据 OpenAPI 规范进行验证。Swagger Editor 还能可视化 API，使团队能够从一开始就记录 API。API 设计优先方法的优势在于，它使您能够设计 API 并使用它来创建 OpenAPI 规范，并且您可以创建模拟服务器来模拟 API 响应。

Swagger Codegen

Swagger Codegen 允许您创建服务器存根（模拟服务器响应 API 调用的代码）和 SDK（软件开发工具包——一组帮助开发人员将您的 API 集成到其系统中的工具）。如果技术文档工程师具备适当的技术知识和经验，有时也会参与到 SDK 的工作中。

Swagger UI

Swagger UI 是技术文档工程师最有可能参与创建 Swagger API 文档的工具。Swagger UI 提供了 API 及其文档的可视化表示。它读取 YAML 或 JSON 文件并将其显示为交互式文档，允许用户在浏览器中尝试 API 调用；展示可用的端点并允许对每个端点进行调用。

Swagger Hub

Swagger Hub 是 Swagger 团队提供的最新产品，它将 Swagger Editor、Swagger Codegen 和 Swagger UI 结合在一个托管环境中，提供统一的界面。

您可以用 Swagger 做什么？

以上是 Swagger 提供的工具，但使用 Swagger，您不仅可以随 API 一起创建文档，还可以为现有 API 编写文档，与任何开发环境集成，并确保符合最新的 OpenAPI 规范。

另请参阅我们关于金融科技API的文章。

谁可以从Swagger中受益？

• OpenAPI定义是纯文本文档，可以存放在任何类型的仓库中，例如GitHub，这意味着可以在协作环境中进行工作。
• 如果速度和可靠性对您的项目很重要，在Swagger编辑器中创建您的API意味着您的开发人员将可以访问自动完成选项和实时错误报告，以确保符合规范；并且使用代码生成器允许您利用Swagger的自动化代码生成SDK。
• 您没有可用的API或开发文档，但您的客户/合作伙伴需要一个。您可以在产品中实现API之前，使用Swagger编辑器设计API，并通过模拟服务器暴露端点。
• API的好坏取决于其文档，毕竟，如果对API的工作原理没有解释、解释不完整或难以使用，我们就无法使用API。Swagger UI允许您轻松地从代码生成文档。

如何使用Swagger创建开发文档

首先，如果您还不熟悉Swagger，我强烈建议您从Swagger官方的Petstore演示开始：https://petstore.swagger.io/。您可以查看Swagger文档站点的外观，可以打开它构建所依据的JSON文件。您可以查看端点及其可用的调用，并在适当的地方尝试GET、PUT、POST和DELETE调用。

自上而下还是自下而上？

采用自上而下的方法意味着从Swagger Editor开始，在创建API的同时创建/编辑开发文档。虽然这对大多数技术写作者来说可能是首选方案，但开发团队通常认为这种方法会减慢API本身的生产速度。

自上而下的开发方法允许新创公司或新项目设计API，并用它来生成OpenAPI规范，这意味着他们可以提供自动化的文档和模拟服务器来模拟API响应。

自下而上的方法（也称为代码优先方法）更为常见，通常涉及技术写作者获取已完成的API，并使用Swagger UI创建在线互动文档。这样，API开发不会因为文档编写而等待。

编辑和审查Swagger文件

使用Swagger Editor允许您加载YAML或JSON定义文件，或从头开始创建新文件。您可以在此处查看使用Petstore规范的Swagger Editor演示：https://editor.swagger.io/。使用Swagger编辑器意味着任何结构或类型错误都会立即引起您的注意，并且您可以看到它们将如何在文档中显示，这意味着可以随时对文件进行必要的更改。

在 Swagger 中创建客户端库

客户端库提供了特定语言的代码块，开发者可以将其添加到他们的项目中，以便与您的 API 进行交互。使用客户端库可以加快开发速度，因为开发者不必从头开始编写所有内容。使用免费工具 Swagger Codegen，您可以直接从您的 Swagger API 为大多数语言（包括 Android、C#、C++、Java、Javascript、Go、ObjC、PHP、Python、Ruby、Scala 等）创建客户端库。Codegen 使用模板驱动的引擎来分析/解析您的 OpenAPI 定义，并为所选语言生成客户端 SDK。

将 Swagger 文档与其他工具集成

作为技术文档工程师，您可能有一个偏好的写作工具，或者您在当前角色中继承了某个工具；无论如何，为了维护“单一事实来源”并避免重复，您需要在某个时间点将您的 API 文档与其他文档集成起来。最简单的方法是在 API 文档中使用“外部文档”对象来引用其他文档。

或者，如果您已经有一个文档站点，API 文档可以嵌入到一个页面中（尽管这最终看起来总是有点笨拙）。最后，您可以使用一个工具来导入您的 Swagger 文档并允许您添加更多内容。例如，像 Readme.com、Stoplight、Apiary 和 Mulesoft 这样的工具允许您导入 Swagger 文档并添加更多内容。虽然您可能也希望让您传统的技术文档工具（如 Flare 和 RoboHelp）整合您的 API 文档，这是可以做到的，但过程相当漫长。

Swagger 开发文档最佳实践

使用Swagger进行开发文档化的最佳实践，在很大程度上与任何文档项目是相同的，但最终受众可能略有不同。例如，虽然我们不是为机器写作，但我们是为技术背景深厚的读者写作，因此内容必须具备可读性，同时直奔主题也非常重要。请包含代码示例和API使用范例。

确保在整个文档中使用一致的术语和语气，这不是小说，因此您不需要不断思考新的表达方式。如果必须使用技术术语、缩写词和/或缩略语，请确保它们是行业标准且被广泛理解的，并在适当时在术语表中加以解释。最后，确保您的文档保持最新；过时的文档可能具有误导性、耗时，并可能对最终用户造成损害。

Swagger 开发文档示例

以下是一些公开的Swagger 开发文档示例：

ETER（欧洲高等教育注册）API

ETER（欧洲高等教育注册）在此处使用Swagger记录了对其数据库的API访问：https://www.eter-project.com/api/doc/。您可以看到他们链接到了其余文档，并列出了所有端点和方法，同时还提供了试用功能。

Nokia Motive Connected Device Platform API Swagger 文档，虽然没有展示任何高层次信息或指向其他文档的链接，但它展示了如何通过 CSS 修改界面外观，以反映您自己的配色方案、字体等。

Connect 公共 API

来自 Objective Corporation 的 Connect 公共 API 文档 展示了良好的介绍性信息水平，并为端点、方法和模式提供了大量解释性文本。

Apache OpenMeetings API

Apache OpenMeetings API 文档 提供了最全面的介绍性文本部分之一，包括其用途、使用方法、示例链接、相关模块链接，以及指向网站和联系团队的链接。

总结

💛🧡🧡客户评价：作为一名与各种客户和系统（定制和基于服务）合作的质量保证分析师，Baklib 是迄今为止最容易与最终用户合作的平台之一。我们与客户合作，在 Baklib 提供的基础上进行定制和构建，以满足他们的业务需求。这种可扩展性确保我们能够满足客户的需求，同时将整体复杂性降至最低。

使用 Swagger 编写 API 文档可以自动化大量的文档工作，并在一定程度上让技术文档工程师的工作变得更简单，但重要的是要记住技术写作的一些关键方面，例如在开始写作之前规划好文档，记住你为谁写作，并确保文档保持最新。

多年来，OpenAPI 规范和 Swagger 一直被当作同义词使用，它最初是 Swagger API 规范，但自从该规范成为 OpenAPI 以来，Swagger 已不再是 OpenAPI 的唯一 API 文档解决方案。现在有更多工具可供选择，作为规划的一部分，你也应该考虑其他工具是否更合适。

永远不要忘记，你的 API 文档只有一个目标：帮助开发者连接到 API 并与其所需的数据进行交互。