NodeJS apidoc文档生成

NodeJS Restful的api文档

一.前言

​ 目前前后端分离的模式,已经深得各大公司的喜爱,然而前后端沟通的成本就增加了,我们的书面文档就成了关键,想想,我们在开发的时候,直接把文档丢给相应的调用接口的人,不管是前端后端,都开心了.按照接口文档的规范去开发,效率会提高很多.

​ 之前我做.net开发的时候,就是用的swagger直接生成文档,还可以在线调试.但是呢有些公司开发的模式各有不同:比如开发的时候,前端不可能一直等着后端把功能模块都搞定之后再生成文档,毕竟是协同开发,所以有的时候,是先有文档,再有接口,不过这种模式,一般是需要功底比较深的开发人员,可以在开发前期就直接定出所有的文档.我们这边呢,今天不说swagger,虽然swagger也可以搭配nodejs生成接口文档,但是我这介绍的是:ApiDoc框架直接生成的api文档.

apidoc官网

二.接口文档

一个规范的接口包含以下内容

• 请求方式
• 请求地址
• 请求参数
• 后端响应4

三.Apidoc生成文档

1. 全局安装

$  npm install apidoc  -g

2.项目根目录配置apidoc.json

{
    "name": "example",
    "version": "0.1.0",
    "description": "apiDoc basic example",
    "title": "Custom apiDoc browser title",
    "url" : "https://api.github.com/v1"
}

• name API接口文档名称
• version API接口文档版本号
• description API接口文档简要描述
• title API接口文档生成的网页标题
• url API接口文档中请求的基本路径

上面是一个方法,其实还有一个方法

2.1 方式二

可以在package.json最后面加,这样相比上面的方式就不用再加一个文件了

 "apidoc": {
    "name": "用户管理",
    "version": "0.1.0",
    "description": "apiDoc 用户管理接口文档",
    "title": "用户管理接口文档",
    "url" : "https://api.github.com/v1"
} 

3.编写Api

/**
 * @api {post} http://localhost:3000/register 用户注册
 * @apiDescription 用户注册
 * @apiName submit-login
 * @apiGroup User
 * @apiParam (body) {String} email 用户邮箱
 * @apiParam (body) {String} password 用户密码
 *
 * @apiSuccess {Number} code 错误状态码.
 * @apiSuccess {String} msg  错误消息.
 * @apiSuccessExample {json} Success-Response:
 *  {
 *      "code" : "0",
 *      "msg" : "注册成功"
 * 
 *  }
 * @apiSampleRequest http://localhost:3000/register
 * @apiVersion 1.0.0
 */
router.post("/register", userController.register);

在路由那块添加以上注释就可以让apidoc识别,生成文档,注解说明可见官网注解说明

4.运行命令,生成文档

命令:

$ apidoc -i ./ -o ./public/apidoc

在package.json中的scripts配置如下

  "scripts": {
    "docs": "apidoc -i ./routers -o ./public/docs",
  }

-i 输入源目录名。项目文件的位置。

-o 输出目录名。放置生成的文档的位置。

通过本地域名去访问:http://localhost:3000/docs/index.html即可

以下是我通过docs生成的可以直接在线调试的api文档,功能简直不要太强大!