在前端开发过程中，RESTful API 是不可或缺的一部分。在设计和开发 API 的过程中，文档的撰写和测试是非常重要的。本文将着重介绍如何进行 RESTful API 的自我文档化和自动化测试，为开发人员提供更加便利的开发体验和更加稳定的 API 系统。
什么是 RESTful API
首先，我们需要明确 RESTful API 是什么。RESTful，全称为 Representational State Transfer，是一种架构风格，通常用于设计 Web 应用程序。它以统一接口为中心，通过 HTTP 协议进行轻量级通信，并通过 URIs(Uniform Resource Identifiers) 来对资源进行操作。
一个 RESTful API 通常有以下特点：
- 基于 HTTP 协议
- 使用标准 HTTP 方法（GET, POST, PUT, DELETE）
- 返回 HTTP 状态码，没有状态信息存储在服务端，即所谓的无状态性(Stateless)
- 对资源进行操作，默认以 JSON 或 XML 格式传输数据
自我文档化
文档是一个 API 非常重要的组成部分。当我们开放一个 API 供他人使用时，良好的文档可以方便他人使用我们的 API，同时能够提高其他开发者学习我们的 API 的效率。因此，自我文档化是 RESTful API 设计的核心。
Swagger
Swagger 是一个非常流行的 RESTful API 文档工具，它可以让我们在开发 API 的同时生成文档。我们可以使用 Swagger 的可视化界面来生成和测试 API，同时它还支持多种编程语言和框架，例如 Node.js、Java、Python 等等。
使用 Swagger 需要在项目中进行相应的配置和文档注释，这里以 Node.js 为例展示一下使用 Swagger 的过程：
- 安装 Swagger
在项目中使用 npm 安装 swagger-ui 和 swagger-jsdoc
npm i swagger-ui swagger-jsdoc --save-dev
- 配置 Swagger
在项目中创建一个 swagger.js，然后进行配置。如下：
-- -------------------- ---- -------
----- ------------ - ------------------------
----- ------- - -
----------- -
-------- --------
----- -
------ ---- ----------
-------- -------
--
-------- -
-
---- -----------------------
-
-
--
----- -----------------
-
----- ----------- - ---------------------
-------------- - -----------可以看到，这里我们定义了一些基本信息，比如 API 的名称、版本号和服务地址等等，然后指定了包含 API 文档注释的文件路径。这样，我们就可以自动生成 API 文档。当然，我们需要在每个接口中添加相应的文档注释。如下：
-- -------------------- ---- ------- --- - -------- - ----- - ----- ---- - ------------ ---- -- --- - -------- - ----------- - ---- - ----- - - ---- - ------------ ------ - --------- - - ---------------- - ---------- - ---- - ------------ ---- - ------- - ----- ------ - ----------- - ------- - ----- ------ - -------- - ----- ------ - ----- - ----- ----- - ------ - ----- ------ - ----------- - --- - ----- ------ - --------- - ----- ------ - --------- - ----- ------ -- -------------------- ----- ---- -- - ------------ --
这里我们使用了 @swagger 标签来进行文档注释。注释可以描述接口信息、参数列表、返回结果等等，Swagger 会读取这些注释来生成相应的文档。
- 展示文档
现在我们已经有了所有的配置和文档，该如何将生成的文档在 web 上展示呢？我们需要安装 swagger-ui-express，然后在路由中添加 Swagger 的路由即可。如下：
const swaggerUi = require('swagger-ui-express')
const swaggerSpec = require('../swagger')
router.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec))现在，我们在浏览器中输入 http://localhost:3000/api-docs，就可以看到我们生成的文档了。
APIDoc
在我们熟悉 Swagger 之前，APIDoc 是一个比较受欢迎的自我文档化工具。APIDoc 和 Swagger 的语法类似，在开发的过程中，我们只需要在 HTTP 请求中添加注释，APIDoc 就会自动生成文档。
使用 APIDoc 需要在项目中进行相应的配置和文档注释，这里以 Node.js 为例展示一下使用 APIDoc 的过程：
- 安装
使用 npm 在项目中安装 APIDoc：
npm i apidoc --save-dev
- 配置
在项目的 package.json 文件中添加启动脚本：
{
"scripts": {
"apidoc": "apidoc -i ./routes -o ./apidoc"
}
}这里我们使用了 routes 目录来生成文档，你也可以使用其他的目录。然后在项目根目录下创建一个 apidoc.json：
-- -------------------- ---- -------
-
------- ---- ----------
---------- --------
-------------- ---- ----------
-------- ---- ----------
----- - -------------------
----------- - -------------------
----------- -
----- -
------- -----
---------- ---------------
-
--
--------- -
-------- -------
----------- -----------
-
-这里我们定义了文档的名称、版本、描述等等。其中，url 为我们自己设置的 API 地址，sampleUrl 是建议使用的 URL，方便用户进行测试。template 中的 ui 可以帮助我们设置 UI 界面的一些参数，从而让文档更加美观。
- 生成文档
在项目中输入以下命令，使用 APIDoc 帮我们生成文档：
npm run apidoc
在接口中向注释传递文档参数， 如下：
-- -------------------- ---- ------- --- - ---- ----- ------ ------ - -------- -------- - --------- ---- - - ----------- -------- ------ --- - ----------- -------- ------- ---- - ----------- ---------- ---- ---- - ----------- -------- ------- ---- - ----------- -------- ------------- --- - ----------- -------- ------------- ---- -- -------------------- ----- ---- -- - ------------ --
这时，我们运行 npm run apidoc 就可以将注释生成文档了。
然后在项目中保存document.md文件，成功把文档转换成文档需要格式，运用github pages 等工具生成在线文档。
自动化测试
自动化测试可以在开发过程中极大地提高代码质量和开发效率。对于 API 服务来说，自动化测试也是非常重要的。自动化测试可以帮助我们发现潜在的问题和缺陷，帮助我们保证 API 的质量和稳定性。
Supertest
Supertest 是一个非常流行的自动化测试工具，它可以帮助我们对 HTTP 服务进行单元测试。这里以 Node.js 为例，展示一下如何使用 Supertest 进行单元测试：
- 安装 Supertest 和 Mocha
在项目中使用 npm 安装 supertest 和 mocha：
npm i supertest mocha chai --save-dev
- 编写测试用例
编写一个测试用例，在测试用例中使用 Supertest 来请求 API 并比较返回结果，验证 API 的正确性。如下：
-- -------------------- ---- -------
----- ------- - --------------------
----- --- - -----------------
----- ------ - ----------------------
-------------- ----- -------- -- -
------- ----- --------- -------- ------ -
------------
--------------
------------
------------- ----- ---- -
-- ----- ------ ---------
-------------------------------------------
---------------------------------------
----------------------------------------
------
--
--
--在这个测试用例中，我们首先使用 require ('supertest') 来引入 Supertest。然后在测试用例中使用 supertest(app) 生成一个测试实例。在实例中使用 HTTP 方法来测试 API，例如这里我们使用了 .get('/users') 来测试 GET 请求。
- 运行测试
在项目中运行以下命令来运行测试：
npm run test
运行成功后，如果测试用例执行正确，就可以显示 All test pass 返回结果。
总结
本文主要介绍了 RESTful API 的自我文档化和自动化测试，它们在 Restful API 开发中起着至关重要的作用。Swagger 和 APIDoc 是最常见的两种自我文档化工具，Supertest 是比较常见的自动化测试工具。在开发过程中，要注意文档和测试的编写和更新，以保证 API 的质量和稳定性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/648c010148841e9894a4af8c