使用 OpenAPI 构建 API 文档

作为一名开发者，往往需要编写程序的 API 文档，尤其是 Web 后端开发者，在跟前端对接 HTTP 接口的时候，一个好的 API 文档能够大大提高协作效率，降低沟通成本，本文就来聊聊如何使用 OpenAPI 构建 HTTP 接口文档。

OpenAPI

什么是 OpenAPI

OpenAPI 是规范化描述 API 领域应用最广泛的行业标准，由 OpenAPI Initiative(OAI) 定义并维护，同时也是 Linux 基金会下的一个开源项目。通常我们所说的 OpenAPI 全称应该是 OpenAPI Specification(OpenAPI 规范，简称 OSA)，它使用规定的格式来描述 HTTP RESTful API 的定义，以此来规范 RESTful 服务开发过程。使用 JSON 或 YAML 来描述一个标准的、与编程语言无关的 HTTP API 接口。OpenAPI 规范最初基于 SmartBear Software 在 2015 年捐赠的 Swagger 规范演变而来，目前最新的版本是 v3.1.0。

简单来说，OpenAPI 就是用来定义 HTTP 接口文档的一种规范，大家都按照同一套规范来编写接口文档，能够极大的减少沟通成本。

OpenAPI 规范基本信息

OpenAPI 规范内容包含非常多的细节，本文无法一一讲解，这里仅介绍常见的基本信息，以 YAML 为例进行说明。YAML 是 JSON 的超集，在 OpenAPI 规范中定义的所有语法，两者之间是可以互相转换的，如果手动编写，建议编写 YAML 格式，更为易读。

OpenAPI 文档编写在一个 .json 或 .yaml 中，推荐将其命名为 openapi.json 或 openapi.yaml，OpenAPI 文档其实就是一个单一的 JSON 对象，其中包含符合 OpenAPI 规范中定义的结构字段。

OpenAPI 规范基本信息如下：

字段名	类型	描述
openapi	string	必选，必须是 OpenAPI 已发布的合法版本，如 3.0.1。
info	object	必选，此字段提供 API 相关的元数据（如描述、作者和联系信息）。
servers	array[object]	这是一个 Server 对象的数组，提供到服务器的连接信息。
paths	object	必选，API 提供的可用的路径和操作。
components	object	一个包含多种结构的元素，可复用组件。
security	array	声明 API 使用的安全认证机制，目前支持 HTTP Basic Auth、HTTP Bearer Auth、ApiKey Auth 以及 OAuth2。
tags	array	提供标签可以为 API 归类，每个标签名都应该是唯一的。
externalDocs	object	附加的文档，可以通过扩展属性来扩展文档。

一个 YAML 格式的 OpenAPI 文档示例如下：

yaml

体验AI代码助手

代码解读

复制代码

openapi: 3.1.0 info: title: Tic Tac Toe description: | This API allows writing down marks on a Tic Tac Toe board and requesting the state of the board or of individual squares. version: 1.0.0 # 此为 API 接口文档版本，与 openapi 版本无关 tags: - name: Gameplay paths: # Whole board operations /board: get: summary: Get the whole board description: Retrieves the current state of the board and the winner. tags: - Gameplay operationId: get-board responses: "200": description: "OK" content: application/json: schema: $ref: "#/components/schemas/status" # Single square operations /board/{row}/{column}: parameters: - $ref: "#/components/parameters/rowParam" - $ref: "#/components/parameters/columnParam" get: summary: Get a single board square description: Retrieves the requested square. tags: - Gameplay operationId: get-square responses: "200": description: "OK" content: application/json: schema: $ref: "#/components/schemas/mark" "400": description: The provided parameters are incorrect content: text/html: schema: $ref: "#/components/schemas/errorMessage" example: "Illegal coordinates" ...

以上示例完整文档在此，具体语法我就不在这里介绍了。如果你开发过 API 接口，相信能看懂文档大部分内容所代表的含义。不必完全掌握其语法，这并不会对阅读本文接下来的内容造成困扰，因为稍后我会介绍如何通过代码注释的方式自动生成此文档。

如果你想手动编写 OpenAPI 文档，那么我还是推荐你阅读下 OpenAPI 规范，这里有一份中文版的规范。阅读规范是一个比较枯燥的过程，如果你没有耐心读完，强烈建议阅读 OpenAPI 规范入门，相较于完整版的规范要精简得多，并且讲解更加易于理解。

另外还推荐访问 OpenAPI Map 网站来掌握 OpenAPI 规范，该网站以思维导图的形式展现规范的格式以及说明。

OpenAPI.Tools

现在我们知道了 OpenAPI 规范，接下来要做什么？当然是了解 OpenAPI 开放了哪些能力。

有一个叫 OpenAPI.Tools 的网站，分类整理并记录了社区围绕 OpenAPI 规范开发的流行工具。

可以看到列表中有很多分类，在我们日常开发中，最经常使用的有三类：

文档编辑器

文档编辑器方便我们用来编写符合 OpenAPI 规范的文档，有助于提高编写文档的效率，就像 VS Code 能够方便我们编写代码一样。

文档编辑器有两种：文本编辑器 以及 图形编辑器。

文本编辑器推荐使用在线的 Swagger Editor，能够实现格式校验和实时预览 Swagger 交互式 API 文档功能，效果如下图所示：

如果你习惯使用 VS Code，也有相应插件可供使用。

图形编辑器的好处是能够以可视化的形式编辑内容，不了解 OpenAPI 规范语法也能编辑。可以根据自己喜好来进行选择，如 Stoplight Studio、APIGit 等。

Mock 服务器

当我们使用 OpenAPI 规范来进行接口开发时，往往采用文档先行的策略，也就是前后端在开发代码前，先定义好接口文档，再进行代码的编写。此时前端如果想测试接口可用性，而后端代码还没有编写完成，Mock 服务器就派上用场了。Mock 服务器能够根据所提供的 OpenAPI 接口文档，自动生成一个模拟的 Web Server。使用 Mock 服务器能够轻松模拟真实的后端接口，方便前端同学进行接口调试。

上面提到的 APIGit 也同时具备此功能。

代码生成器

还有一种很实用的工具是代码生成器，代码生成器有两种类型：一种是从代码/注释生成 OpenAPI 文档，另一种是从 OpenAPI 文档生成代码。

这类工具同样非常多，且更为实用。比如我们有一份写好了的 Go Web Server 代码，想要自动生成一份 OpenAPI 文档，就可以使用 go-swagger 这个工具来生成一份 openapi.yaml 文档。

而如果我们有一份 openapi.yaml 文档，就可以利用 go-swagger 生成一份 Go SDK 代码，甚至它还能根据这份 OpenAPI 文档生成 Go Web Server 的框架代码，我们只需要在对应的接口里面实现具体的业务逻辑即可。

不仅 Go 语言有这样的工具，像 Swagger Codegen 和 OpenAPI Generator 这类工具更是支持几乎所有主流编程语言。

代码生成器是开发者应该着重关注的工具，使用这些工具可以减少大量手动且重复的工作，你可以在此看下有没有感兴趣的项目供你使用。

Swagger

什么是 Swagger

Swagger 是一套围绕 OpenAPI 规范所构建的开源工具集，提供了强大和易于使用的工具来充分利用 OpenAPI 规范，Swagger 工具集由最初的 Swagger 规范背后的团队所开发。

Swagger 工具集提供了 API 设计、开发、测试、治理和监控等能力，其中最主要的工具包含如下三个：

• Swagger Codegen：根据 OpenAPI 规范定义生成服务器存根和客户端 SDK。

• Swagger Editor：基于浏览器的在线 OpenAPI 规范编辑器。

• Swagger UI：以 UI 界面的方式可视化展示 OpenAPI 规范定义，并且能够在浏览器中进行交互。

当然 Swagger 也有为企业用户提供的收费版本工具，如 SwaggerHub Enterprise，感兴趣的同学可以自行了解。

Swagger 和 OpenAPI 的关系

讲到了 Swagger，就不得不提及 Swagger 和 OpenAPI 的联系与区别，因为这二者经常在一起出现。

前文也说过 OpenAPI 规范是基于 Swagger 规范演变而来的，但其实二者并不相等。

在 OpenAPI 尚未出现之前，Swagger 代表了 Swagger 规范以及一系列围绕 Swagger 规范的开源工具集。Swagger 规范最后一个版本是 2.0，之后就捐赠给了 OAI 并被重新命名为 OpenAPI 规范，所以 OpenAPI 规范第一个版本是 2.0，也就是 Swagger 规范 2.0，而由 OAI 这个组织发布的第一个 OpenAPI 规范正式版本是 3.0.0。

现在，Swagger 规范已被 OpenAPI 规范完全接管并取代。OpenAPI 代表了 OpenAPI 规范以及一系列生态，而 Swagger 则是这个生态中的一部分，是 Swagger 团队围绕 OpenAPI 规范所开发的一系列工具集。

Swagger 是 OpenAPI 生态中非常重要的组成部分，因为它给出了一整套方案，且非常流行。

Swagger 和 OpenAPI 二者 LOGO 对比如下：

希望你下次再见到这两个 LOGO 时能清晰分辨出二者，而不被混淆。

以 Go 语言为例讲解 OpenAPI 在实际开发中的应用

前文介绍了编写 OpenAPI 文档的两种编辑器：文本编辑器以及图形编辑器。在日常开发中，后端可以先使用这类编辑器如 Swagger Editor 编写出 OpenAPI 文档，然后将这份文档交给前端，前端拿到 OpenAPI 文档后将其导入到 Swagger Editor，就可以在线阅读接口文档并与之进行交互，之后前后端就可以并行开发了。

这样的工作流看起来似乎没什么问题，不过编写 OpenAPI 文档毕竟是个苦力活，不仅有大量的重复工作，还要求开发者熟练掌握 OpenAPI 规范语法。这对于“爱偷懒”的开发者显然是无法接受的，就像段子里说的，程序员最讨厌两件事：1. 写文档，2. 别人不写文档。而这个问题的解法，当然就是前文提到的代码生成器。

使用 Swag 生成 Swagger 文档

在 Go 语言生态里，目前有两个比较流行的开源工具可以生成 Swagger 文档，分别是 go-swagger 和 swag。它们都能根据代码中的注释生成 Swagger 文档，go-swagger 作为一款 OpenAPI.Tools 推荐的工具，其功能比 swag 更加强大且 Github Star 数量也更高。

不过本文将选择 swag 来进行介绍，一是因为 swag 比较轻量，更适合微服务开发；二是如果使用 swag，那么注释代码会离接口代码更近，升级时方便维护。如果你有更高级的需求，如根据 Swagger 文档生成客户端 SDK，服务端存根等，则推荐使用 go-swagger。

注意：在这里我一直提到的都是生成 Swagger 文档，而没有说是 OpenAPI 文档。因为无论是 swag 还是功能更强大的 go-swagger，它们目前都仅支持生成 OpenAPI 2.0 文档，并不支持生成 OpenAPI 3.0+ 文档，而 OpenAPI 2.0 版本我们更习惯称其为 Swagger 文档。