Swagger API：工作原理及您需要了解的内容

什么是 Swagger？

Swagger 是一个广泛应用于 API 开发和文档编写的工具集。它通过提供一套开源工具和服务，帮助开发者和技术文档编写者更高效地设计、构建和维护 API 文档。以下内容将详细介绍 Swagger 的核心工具及其功能。

API 文档的 Swagger 工具

Swagger 提供了一系列开源工具，支持 API 的开发和文档编写。以下是主要工具的功能简介：

Swagger 编辑器

Swagger 编辑器是一个用于设计和构建 RESTful API 的工具，支持基于 OpenAPI 规范的验证。通过 Swagger 编辑器，开发团队可以在 API 开发的早期阶段记录 API。其主要特点包括：

可视化 API 设计，便于团队协作。
支持 API 设计优先的开发方法，生成 OpenAPI 规范。
提供模拟服务器功能，用于模拟 API 响应。

Swagger 编码器（Swagger Codegen）

Swagger Codegen 是一个强大的工具，用于生成服务器存根代码和客户端 SDK（软件开发工具包）。它的主要功能包括：

自动生成模拟服务器代码，快速响应 API 调用。
提供多种编程语言的 SDK，便于开发者将 API 集成到项目中。
技术文档作者在具备一定技术背景时，也可以参与 SDK 的编写。

Swagger UI（用户界面）

Swagger UI 是一个交互式工具，用于可视化展示 API 文档。它的主要特点包括：

将 YAML 或 JSON 格式的 API 定义文件转换为交互式文档。
支持用户直接在浏览器中测试 API 调用。
显示所有可用端点，并允许对每个端点进行调用。

Swagger Hub

Swagger Hub 是 Swagger 团队推出的最新产品，它将 Swagger Editor、Swagger Codegen 和 Swagger UI 集成在一个托管环境中，为团队协作提供了便利。

使用 Swagger 的主要功能

借助 Swagger 工具，用户可以完成以下任务：

记录现有 API，并确保其符合最新的 OpenAPI 规范。
与任何开发环境集成，提升开发效率。
在产品开发前，通过模拟服务器公开端点，便于测试和验证。
自动生成交互式文档，提升 API 的可用性。

谁能从 Swagger 中受益？

以下是一些可以从 Swagger 中获益的场景和用户：

开发团队：通过 Swagger Editor 提供的自动完成和实时错误报告功能，确保 API 开发符合规范。
技术文档作者：使用 Swagger UI 快速生成交互式文档，减少文档编写的复杂性。
初创企业：通过 Swagger 的设计生成 OpenAPI 规范。
客户与合作伙伴：即使没有现成的 API 文档，也可以通过 Swagger 提供的工具快速生成。

如何使用 Swagger 创建 API 文档

从 Petstore 演示开始

如果您是 Swagger 的新手，可以从官方的 Petstore 演示开始：https://petstore.swagger.io/。该演示展示了 Swagger 文档的外观，并允许用户查看 JSON 文件、端点及其调用方式，还可以尝试 GET、PUT、POST 和 DELETE 调用。

自上而下 vs 自下而上

自上而下方法：从 Swagger 编辑器开始，设计 API 并生成 OpenAPI 规范。这种方法适合初创企业或新项目，但可能会延缓 API 的实际开发。
自下而上方法：从现有 API 开始，通过 Swagger UI 创建交互式文档。这种方法更常见，适合已经完成开发的 API。

创建客户端库

Swagger Codegen 支持生成多种编程语言的客户端库，包括 Android、C#、Java、Python 等。通过模板驱动引擎，用户可以快速生成与 API 交互的代码块，加速开发进程。

集成 Swagger 文档与其他工具

为了实现文档的统一管理，您可以将 Swagger 文档与其他工具集成。例如：

使用 “外部文档” 对象引用其他文档。
将 API 文档嵌入现有的网站。
借助 Readme.com、Stoplight 等工具导入 Swagger 文档，并添加更多内容。

Swagger API 文档最佳实践

在使用 Swagger 编写 API 文档时，请遵循以下最佳实践：

保持术语一致：使用行业标准的术语和缩写，并在必要时提供术语表。
提供代码示例：通过示例帮助用户理解 API 的使用方法。
确保文档更新：过时的文档会误导用户，甚至对最终用户造成损害。
简洁明了：针对技术性强的受众，内容应直击要点。

Swagger API 文档示例

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

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

ETER 使用 Swagger 记录其数据库访问 API。文档中列出了所有端点和方法，并提供了尝试调用的功能。详情请访问：https://www.eter-project.com/api/doc/

诺基亚移动互联设备平台 API

诺基亚的 Swagger 文档展示了如何通过 CSS 修改界面外观，以反映自定义的配色方案和字体。

Apache OpenMeetings API

Apache OpenMeetings 的文档提供了详细的介绍性文本，包括用途、使用方法、示例链接和相关模块链接。

总结

Swagger 是一个功能强大的工具集，能够显著提升 API 开发和文档编写的效率。无论是开发团队还是技术文档作者，都可以通过其提供的编辑器、编码器和用户界面工具，快速生成符合 OpenAPI 规范的文档。同时，遵循最佳实践并保持文档更新，能够进一步提升 API 的可用性和用户体验。

原文链接: https://document360.com/blog/swagger-api/