在前端开发中，为了让后端开发者更快更好地了解我们前端业务的具体接口实现，我们经常需要编写接口文档，这是非常重要的一个工作。在接口文档的构建过程中，我们需要手动撰写文档并对其中的每个接口进行详细描述，这对于工作量和效率都有一定的影响。针对这个问题，我们可以使用一个叫做 api-doc-generator 的 npm 包，它可以快速地根据我们编写的注释自动生成接口文档，极大地提高了我们的工作效率。
本文将为大家介绍如何使用 api-doc-generator 这个工具来生成接口文档。
什么是 api-doc-generator
api-doc-generator 是一个基于 jsdoc 依赖的 npm 包，通过在我们代码中添加 jsdoc 注释的方式来自动生成我们的接口文档。它提供了一组完整的命令行工具和配置文件，可以简单而快速地配置、自定义和生成我们的接口文档。
api-doc-generator 的使用方法
下面将介绍如何使用 api-doc-generator 来生成接口文档。
安装 api-doc-generator
使用 npm 命令来安装 api-doc-generator：
npm install api-doc-generator --save-dev
配置 jsdoc
添加 jsdoc 注释到我们的代码中，以便 api-doc-generator 可以生成我们的接口文档。下面是三个样例注释：
-- -------------------- ---- ------- --- - ---- ------ ------ ---- - -------- ----- - --------- ---- - - --------- -------- -------- --- - --------- -------- -------- -- - - ----------- -------- ---- --- - ----------- -------- ------- ---- - ----------- -------- ---- ---- --
@api {post} /login：定义请求方法和路径，post 表示是 post 请求，/login 表示请求路径。@apiName login：定义接口名称。@apiGroup User：定义接口分组名称，可以在后面统一显示。@apiParam：定义请求参数，使用在请求体中的参数。@apiSuccess：定义响应成功的数据格式。
更多的 API 文档语法可以在官网上找到。
配置 api-doc-generator
创建一个配置文件，命名为 api-doc.json，把它放在项目的根目录下。
-- -------------------- ---- -------
-
------- --------
---------- --------
-------------- ------------
-------- ------------
------ -------------------------
----------- -
-------------- ----
-
-name：文档的名称。version：文档的版本号。description：文档的描述信息。title：文档的标题。url：文档的访问地址，用于显示 API 文档界面地址。template：模板，选择不同的模板会有不同的可选配置。
运行 api-doc-generator
修改 package.json 文件，添加一个 script 命令：
{
"scripts": {
"doc": "apidoc -i ./ -o ./docs -t node_modules/api-doc-generator/template"
}
}doc：命令名称，可以自己定义。-i ./：输入的文件夹，我们的源代码所在的文件夹。-o ./docs：输出的文件夹，我们生成的 API 文档所在的文件夹。-t node_modules/api-doc-generator/template：使用的模板文件夹。
运行 npm run doc 命令，即可在我们的项目中的 ./docs 文件夹中找到我们生成好的 API 文档。
示例代码
下面是一个完整的示例代码：
-- -------------------- ---- -------
---
- ---- ------ ------ ----
- -------- -----
- --------- ----
-
- --------- -------- -------- ---
- --------- -------- -------- --
-
- ----------- -------- ---- ---
- ----------- -------- ------- ----
- ----------- -------- ---- ----
--
--------------------- ----- -------- ----- ----- -
----- - --------- -------- - - -----------------
----- ------ - ----- ------- --------- -------- ---
-- -------- -
-------- - -
----- ----
-------- ----------
----- ------
--
- ---- -
-------- - -
----- ----
-------- ---- ------
--
-
----- -------
---总结
api-doc-generator 是非常优秀的 npm 包，可以让我们在编写接口文档的时候不再需要花费大量时间和精力，可以快速地生成完整的接口文档并分类展示。希望这篇文章对你有所帮助，祝你越来越优秀！
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6005597281e8991b448d6f7f