EasyDSS流媒体解决方案之接口文档自动生成

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

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

1. 使用apidoc

npm install apidoc -g

2. 创建apidoc.json

{    "name": "EasyDSS流媒体解决方案API文档",    "version": "0.1.0",    "description": "",    "title": "EasyDSS流媒体解决方案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: "easyums/admin/",                dest: "doc/EasyDSS_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文档，在修改中会自动生成！

更多EasyDSS相关功能及版本下载

Web：www.easydss.com

EasyDSS技术交流群：560148162