Nodejs项目中快速配置生成接口文档

Nodejs项目如何快速快速生成接口文档？

开发过程中，除了定义接口及开发实现，也需要提供专业的文本来描述对外开发的接口，那么我们该怎么快速的提供文档呢？

1. 使用apidoc

npm install apidoc -g

2. 创建apidoc.json

{
    "name": "LiveQing流媒体解决方案API文档",
    "version": "0.1.0",
    "description": "",
    "title": "LiveQing流媒体解决方案API文档",
    "url": "",
    "sampleUrl": "",
    "header": {
        "title": "",
        "filename": "doc/header.md"
    },
    "footer": {
        "title": "",
        "filename": "doc/footer.md"
    },
    "template": {
        "withCompare": true,
        "withGenerator": true
    }
}

3. grunt配置监听自动化生成

npm i grunt-apidoc --save-dev

在Gruntfile.js添加

grunt.loadNpmTasks('grunt-apidoc');

apidoc: {
            mypp: {
                src: "test/admin/",
                dest: "doc/LiveQing_API/",
                options: {
                    debug: true,
                    includeFilters: [".*\\.js$"],
                    excludeFilters: ["node_modules/"]
                }
            }
        }
        

watch中加入监听的js文件

grunt

3. 注释编辑API示列

/**
 * @api {get} /user/:id Read data of a User
 * @apiVersion 0.3.0
 * @apiName GetUser
 * @apiGroup User
 * @apiPermission admin
 *
 * @apiDescription Compare Verison 0.3.0 with 0.2.0 and you will see the green markers with new items in version 0.3.0 and red markers with removed items since 0.2.0.
 *
 * @apiParam {Number} id The Users-ID.
 *
 * @apiExample Example usage:
 * curl -i http://localhost/user/4711
 *
 * @apiSuccess {Number}   id            The Users-ID.
 * @apiSuccess {Date}     registered    Registration Date.
 * @apiSuccess {Date}     name          Fullname of the User.
 * @apiSuccess {String[]} nicknames     List of Users nicknames (Array of Strings).
 * @apiSuccess {Object}   profile       Profile data (example for an Object)
 * @apiSuccess {Number}   profile.age   Users age.
 * @apiSuccess {String}   profile.image Avatar-Image.
 * @apiSuccess {Object[]} options       List of Users options (Array of Objects).
 * @apiSuccess {String}   options.name  Option Name.
 * @apiSuccess {String}   options.value Option Value.
 *
 * @apiError NoAccessRight Only authenticated Admins can access the data.
 * @apiError UserNotFound   The <code>id</code> of the User was not found.
 *
 * @apiErrorExample Response (example):
 *     HTTP/1.1 401 Not Authenticated
 *     {
 *       "error": "NoAccessRight"
 *     }
 */
function getUser() { return; }

/**
 * @api {post} /user Create a new User
 * @apiVersion 0.3.0
 * @apiName PostUser
 * @apiGroup User
 * @apiPermission none
 *
 * @apiDescription In this case "apiErrorStructure" is defined and used.
 * Define blocks with params that will be used in several functions, so you dont have to rewrite them.
 *
 * @apiParam {String} name Name of the User.
 *
 * @apiSuccess {Number} id         The new Users-ID.
 *
 * @apiUse CreateUserError
 */
function postUser() { return; }

/**
 * @api {put} /user/:id Change a User
 * @apiVersion 0.3.0
 * @apiName PutUser
 * @apiGroup User
 * @apiPermission none
 *
 * @apiDescription This function has same errors like POST /user, but errors not defined again, they were included with "apiErrorStructure"
 *
 * @apiParam {String} name Name of the User.
 *
 * @apiUse CreateUserError
 */
function putUser() { return; }

如果到这里，恭喜已经生成了API文档，在修改中会自动生成！