RESTful API 是现代 Web 开发中非常重要的一环，它可以让不同的应用程序之间更方便地交换数据。RESTful API 的一个关键点是文档，它必须详细描述 API 的每个端点、可用参数和返回值。在本文中，我们将介绍如何使用 OpenAPI 来构建 RESTful API 文档。
什么是 OpenAPI？
OpenAPI（原名 Swagger）是一个开放源代码的框架，它可以帮助开发者设计、构建、记录和使用 RESTful API。OpenAPI 提供了一种标准的方式来描述 API，包括端点、参数、返回值和错误信息。它还提供了许多工具和库，可以自动生成 API 文档、客户端代码和服务器代码。
如何使用 OpenAPI？
定义 API
使用 OpenAPI 定义 API 可以采用 YAML 或 JSON 格式。下面是一个示例：
-- -------------------- ---- -------
-------- -----
-----
------ -- ---
-------- -----
--------
- ---- ---------------------
------
-------
----
-------- --- - ---- -- -----
------------ ------- - ---- -- -----
----------
------
------------ --
--------
-----------------
-------
----- -----
------
----- ------
-----------
---
----- -------
-----
----- ------
-----
-------- --- - --- ----
------------ ---- - --- ---- -- --- ------
------------
--------- ----
--------
-----------------
-------
----- ------
-----------
-----
----- ------
----------
------
------------ -------
------
------------ --- -------这个示例定义了一个 /users 端点，它支持 GET 和 POST 请求。GET 请求返回一个用户列表，POST 请求用于添加一个新用户。每个端点都有一个 summary（概述）和 description（描述），用于描述端点的作用。每个请求都有一个 response（响应），它描述了请求的结果。对于 POST 请求，还定义了一个 requestBody（请求体），它描述了请求中包含的数据。
生成文档
一旦定义了 API，就可以使用 OpenAPI 工具来生成文档。最流行的工具是 Swagger UI，它可以自动生成一个漂亮的文档，包含端点、参数和响应的详细描述。Swagger UI 还提供了一个交互式界面，可以让用户测试 API。
要使用 Swagger UI，只需将生成的 YAML 或 JSON 文件放在一个 Web 服务器上，然后打开 Swagger UI 页面。例如，如果你将 YAML 文件保存为 api.yaml 并将它放在 http://localhost:8080/api.yaml，那么你可以使用以下代码来启动 Swagger UI：
-- -------------------- ---- -------
--------- -----
------
------
----- --------------- --
-------------- ----------
-----
----------------
---------------
----------------------------------------------------------------------------------
--
-------
------
---- ----------------------
------- -------------------------------------------------------------------------------------------------
------- ------------------------------------------------------------------------------------------------------------
--------
------------- - ---------- -
----- -- - -----------------
---- ---------------------------------
------- --------------
-------- -------------------------------
------- -------------
---
--
---------
-------
-------这个页面将自动加载 Swagger UI，并使用 api.yaml 文件作为文档。你可以在浏览器中打开这个页面，然后浏览 API 文档。
生成客户端代码
除了生成文档外，OpenAPI 还可以自动生成客户端代码。例如，你可以使用 Swagger Codegen 工具来生成 JavaScript 客户端代码：
swagger-codegen generate -i api.yaml -l javascript -o client
这个命令将使用 api.yaml 文件作为输入，生成 JavaScript 客户端代码，并将代码保存在 client 目录中。你可以将这个目录复制到你的项目中，并使用它来调用 API。
生成服务器代码
最后，OpenAPI 还可以自动生成服务器代码。例如，你可以使用 Swagger Codegen 工具来生成 Node.js 服务器代码：
swagger-codegen generate -i api.yaml -l nodejs-server -o server
这个命令将使用 api.yaml 文件作为输入，生成 Node.js 服务器代码，并将代码保存在 server 目录中。你可以将这个目录复制到你的项目中，并使用它来实现 API。
总结
OpenAPI 是一个非常有用的工具，它可以帮助我们定义、记录和使用 RESTful API。使用 OpenAPI，我们可以轻松地生成文档、客户端代码和服务器代码。希望这篇文章能够帮助你更好地理解 OpenAPI，以及如何使用它来构建 RESTful API。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/65d8399e1886fbafa45e3d1d