大前端

主题

使用 apidoc 在 Nodejs 中生成接口文档 ​

一.什么是 apidoc ​

apidoc 是一个简单的 RESTful API 文档生成工具，它从代码注释中提取特定格式的内容生成文档。支持诸如 Go、Java、C++、Rust 等大部分开发语言，具体可使用 apidoc lang 命令行查看所有的支持列表。

常见的生成 api 接口文档的工具还有 swigger，apidoc 的使用文档可以参考apidoc 官网，只是官网是英文的，中文站点可以参考这篇文章：https://blog.csdn.net/qq_14824885/article/details/87793476

二. apidoc 特点 ​

1、跨平台，linux、windows、macOS 等都支持； 2、支持语言广泛，即使是不支持，也很方便扩展； 3、支持多个不同语言的多个项目生成一份文档； 4、输出模板可自定义； 5、根据文档生成 mock 数据；

三. apido 使用 ​

（一）安装 ​

要使用，首先都是安装

shell
# 全局安装
$ npm install apidoc -g

# 若是只在项目里面使用，也可以只是项目内安装
$ npm install apidoc -D

注意：

  • 如果最新版本的 apidoc 生成的接口文档样式有问题，那就请安装老版本：0.29 版本
  • 如果你想在项目中使用，不依赖于全局环境，就是要-D 安装到项目中:cnpm i apidoc -D

（二）创建 apidoc 配置文件 ​

两种方法，任选其一即可

方法一：项目根目录创建 apidoc.json 文件 ​

json
// apidoc.json
{
  "name": "mr_li博客项目",
  "version": "1.0.0",
  "description": "mr_li博客API文档",
  "title": "mr_li博客API文档", //接口文档网页title
  "version": "1.0.0",
  "url": "http://127.0.0.1:5000", // api接口测试请求的地址(必须正确)
  "sampleUrl": "http://127.0.0.1:5000" // 文档中发起测试请求的参数
}

方法二：在 package.json 内添加节点 ​

json
{
  "apidoc": {
    "title": "mr_li博客API文档", //接口文档网页title
    "url": "http://localhost:3000" //api接口测试请求的地址(必须正确)
  }
}

（三）在你写的接口的 js 文件中添加 apidoc 规定的注释 ​

js
/**
 * 假设当前文件的位置为express-demo/router/user.js (express-demo为项目文件夹)
 * @api {get} /user/userInfo 请求用户数据接口
 * @apiName getUserInfo
 * @apiGroup 用户管理
 *
 * @apiParam {Number} id 用户Id.
 *
 * @apiParamExample 请求示例:
 * http://127.0.0.1:3000/api/v1/user/userInfo?id=123
 *
 * @apiSuccess {Number} code 返回码，0正常，其他异常
 * @apiSuccess {String} username 用户名.
 * @apiSuccess {String} age  年龄.
 *
 * @apiSuccessExample 成功响应示例:
 * {
 * "code": 0,
 *   "username": "zs",
 *   "age": 12
 * }
 * @apiError {Number} code 失败的code:1
 * @apiError {String} msg  错误信息提示
 *
 * @apiErrorExample 错误响应示例:
 * {
 *   code: 1,
 *   msg: "参数pageNum格式错误：required"
 * }
 */
function getUserInfo() {}

（四）生成 API 文档 ​

shell
apidoc -i ./router -o ./public/apidoc

即可自动生成接口文档， 文档目录位于 express-demo/public/apidoc 目录下

更进一步，在 package.json 的 scripts 节点下，新增一个 apidoc 节点

json
{
  "scripts": {
    "start": "node index.js",
    "apidoc": "apidoc -i ./router -o ./public/apidoc"
  }
}

对命令进行解释apidoc 去读取 -i 后面的所有文件，对文件内有注释的地方生成文档， 输出到 -o 后面的文件夹

更对参数详解

参数
描述
-h, --help查看帮助文档
-f --file-filters指定读取文件的文件名过滤正则表达式(可指定多个)例如: apidoc -f “..js" − f " . ∗ . t s " -f ".\.ts"−f".∗.ts” 意为只读取后缀名为 js 和 ts 的文件默认值:.clj .cls .coffee .cpp .cs .dart .erl .exs? .go .groovy .ino? .java .js .jsx .kt .litcoffee lua .p .php? .pl .pm .py .rb .scala .ts .vue
-e --exclude-filters指定不读取的文件名过滤正则表达式(可指定多个)例如:apidoc -e “.*.js$” 意为不读取后缀名为 js 的文件默认:’’
-i, --input指定读取源文件的目录例如：apidoc -i myapp/ 意为读取 myapp/目录下面的源文件默认值:./
-o, --output指定输出文档的目录例如：apidoc -o doc/ 意为输出文档到 doc 目录下默认值:./doc/
-t, --template指定输出的模板文件例如:apidoc -t mytemplate/默认:path.join(__dirname, ‘…/template/’)(使用默认模板)
-c, --config指定包含配置文件(apidoc.json)的目录例如:apidoc -c config/默认:./
-p, --private输出的文档中是否包含私有 api 例如:apidoc -p true 默认:false
-v, --verbose是否输出详细的 debug 信息例如:apidoc -v true 默认:false

访问：http://127.0.0.1:3000/apidoc/index.html 前提是要将 public 开启静态资源访问服务，例如 express 里面开启 添加代码到入口文件 app.use(express.static('./public'))

若是想在局域网内的用户也能访问你的 api 接口文档，可以将 apidoc.json 文件内的地址改成你的 IP 地址，再生成一次即可 也可以将生成的 apidoc 放到服务器，用 nginx 启动，供外网访问

生成的 apidoc 文档示例图：(借用的百度上的图片)

图片