作为后台根据需求文档开发完成接口后,交付给前台(angular vue 等)做开发,不可能让前台每个接口调用都去查看你的后台代码一点点查找。前台开发若不懂你的代码呢?让他一个接口一个接口去问你怎么调用,需要传递那些参数?调用方法?这样的话,微信公众号之类的二次开发去找谁要接口调用,这显然是不切合实际的。所以有一个后台接口调用的展示文档,对前后端分离的开发来说,非常实用。之前在. net 开发中使用过 swagger 作为后台接口 API 文档的生成方式。感觉很简单,一步到位。下面介绍一下在 nodejs 中采用 apidoc 来生成 Restful API 的接口文档。
1. 首先 APIDOC 的官网,关于配置等内容可以参看说明
2. 具体操作说明:
1) 安装 node 环境(这个不多说),安装 apidoc
- npm install apidoc - g
2) 打开你的项目,在根目录创建一个配置文件 apidoc.json,里边的内容可参考我的配置:
- {
- "name": "cms-server", // 你的项目名称,可以随便写
- "version": "1.0.0", // 版本,书写没要求
- "description": "cms-server项目API文档", // API文档的描述
- "title": "cms-server API", // API文档的标题
- "url" : "http://localhost:3001/v1", // 项目接口的地址,如我的user接口:localhost:3001/v1/user
- "sampleUrl": "http://localhost:3001/v1",
- "forceLanguage":"zh-cn",
- "template": {
- "withCompare": true,
- "withGenerator": true
- }
- }
3) 新建一个文件夹,用于存放你的 APIDOC 生成的文件,然后在项目的启动文件,如 app.js 添加下边一句话
- app.use('/apidoc存放的位置',express.static('apidoc存放的位置'));
- // 配置实例:若我放在public/apidoc,则对应配置为
- app.use('/public',express.static('public'));
- // 那么我访问的地址应该是:
- // localhost:3001/public/apidoc,他就会自动运行apidoc下生成的apidoc/index.html
4) 在对应的接口上添加注释,可参考下边的配置
- /**
- * 获得某个用户
- * @api {GET} /api/users/:id 获得某个用户
- * @apiDescription 根据ID获得某个用户
- * @apiName getUser
- * @apiParam (path参数) {Number} id
- * @apiSampleRequest /api/users/5a45cefd080d7c39a036ca55
- * @apiGroup User
- * @apiVersion 1.0.0
- */
5) 生成 API 文档
- //apidoc -i '扫描接口的文件夹' -o '生成apidoc的位置'
- //如:
- apidoc - i app / api - o public / apidoc
6) 启动项目,访问 http:localhost:3001/public/apidoc,就可以看到生成的 api 文档。
参考生成的 api 文档:
来源: http://www.bubuko.com/infodetail-2448066.html