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 id 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文档，在修改中会自动生成！

本文来自互联网用户投稿，文章观点仅代表作者本人，不代表本站立场，不承担相关法律责任。如若转载，请注明出处。 如若内容造成侵权/违法违规/事实不符，请点击【内容举报】进行投诉反馈！