How does the Nodejs project generate interface documentation quickly and quickly?

In the development process, in addition to the definition of the interface and the development of implementation, but also need to provide professional text to describe the external development of the interface, so we how to quickly provide documentation?

1. Use apidoc

npm install apidoc -g
Copy the code

2. Create apidoc. Json

{"name": "LiveQing Streaming Media Solution API documentation ", "version": "0.1.0", "description": "", "title": "LiveQing Streaming Media Solution API documentation ", "URL ": "", "sampleUrl": "", "header": { "title": "", "filename": "doc/header.md" }, "footer": { "title": "", "filename": "doc/footer.md" }, "template": { "withCompare": true, "withGenerator": true } }Copy the code

3. Configure automatic generation of grunt listeners

npm i grunt-apidoc --save-dev
Copy the code
In Gruntfile. Js added
grunt.loadNpmTasks('grunt-apidoc');
Copy the code
apidoc: {
            mypp: {
                src: "easyums/admin/",
                dest: "doc/LiveQing_API/",
                options: {
                    debug: true,
                    includeFilters: [".*\\.js$"],
                    excludeFilters: ["node_modules/"]
                }
            }
        }
        
Copy the code
Add listening JS file to watch
grunt
Copy the code

3. Comments edit API listing

/** * @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 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; }Copy the code
If you get to this point, you have generated the API documentation, which will be generated automatically when you modify it!

For more information

Security streaming media Internet live -QQ exchange group: 615081503

Gb GB28181 Without liveGBS-QQ communication group: 947137753

WEB：www.liveqing.com