Web API Document Generation tool Apidoc

apidocYou can generate documents based on code comments, web api support most of the mainstream languages, and, java javascript php coffeescript erlang perl python ruby go... relatively speaking, web interface annotations are easier to maintain and do not require additional maintenance of a document.

apidocGenerate a static html Web page document from a comment that supports not only the project version number, but also the API version number.

Installation

Home: http://apidocjs.com
Github:https://github.com/apidoc/apidoc
Can be used npm install apidoc -g for installation and 0.12.x/4.0 can now be used.

apidocSupport Grunt , Home Https://github.com/apidoc/grunt-apidoc

1. Use the installation in your project npm install grunt-apidoc --save-dev .
2. In the Gruntfile.js add grunt.loadNpmTasks(‘grunt-apidoc‘); .
3. Configurationgrunt task

Apidoc: {      MyApp: {        "app/",        "apidoc/ "       }}

// 在sails中2和3可以直接添加一个task

Module.exports = function (grunt) {    grunt.config. Set ('clean', {      apidoc: {        MyApp:          {'app/'  ,          "apidoc/"}}    );    Grunt.loadnpmtasks ('grunt-apidoc');};

Usage

You can shell apidoc -h see a lot of usage by doing it in.

Here are some common parameters.

// Typical usage " . *\.js$ "-I represents the input, followed by the folder path -o for output, followed by the folder path by default with "apidoc": {} -F is a file filter, followed by a regular expression, the example is to select only the JS file  and -f similar, there is an-e option to exclude the file/ folder, but also use regular expressions if the project input and output is stable, You can edit the makefile Save command, for example    : Docs:-i api/-o doc/apidoc

The make docs API documentation can be generated/updated after use.

Configuring the project configuration

apidoc.jsonExample:

{  "name":"mysails",  "version":"1.0.0",  "title":"mysails",//Browser title  "Description":"Xun ' s test Project"}

If put package.json in, the same field can be directly used package.json by the definition, additional fields are placed apidoc under

{  "name":"mysails",  "Private":true,  "version":"1.0.0",  "Description":"Xun ' s test Project",  "Apidoc": {    "title":"mysails"  },  ...}

Code comments

apidocThe following keywords are supported

@api {Method} path [title] only comment blocks that use the @api callout will generate the document after parsing, and the title will be parsed into a small menu under the navigation menu (@apiGroup) method can have spaces, such as {POST get}@ Apigroup name group names, resolved to the navigation bar menu @apiname name interface names, under the same @apigroup, the same name @api by @apiversion distinction, @api will overwrite the previously defined @api@apidescription text interface description, support HTML syntax @apiversion Verison interface version, Major.minor.patch form @apiignore [hint ] Apidoc ignores interfaces that use @apiignore annotations, hint test addresses to describe @apisamplerequest URL interfaces for testing, and @api method must be post when sending requests/get and so on one of the @apidefine name [title] [description] defines a comment block (not including @api), with @apiuse use can introduce comment block @apiuse@apiuse name can not be used inside @apidefine to introduce a @apidefine comment block @apiparam [(group)] [{type}] [Field=DefaultValue] [Description] @apiHeader [(group)] [{type}] [Field=DefaultValue] [Description] @apiError [(group)] [{type}] field [description] @apiSuccess [(group)] [{type}] field [description] usage is basically similar, Description of the request parameters, headers, response errors and Success group to represent the grouping of parameters, type representation (no spaces), the parameters can be defined by default (no spaces) @apiParamExample [{type}] [title] Example@apiheaderexample [{type}] [title] example@apierrorexample [{type}] [title] example@apisuccessexample [{type}] [Title] Example usage is exactly the same, but type represents the example language type example what will be parsed, so it is best to write when you pay attention to formatting, (many editors have column mode, you can use the column mode to quickly add code *@apiPermission name name must be unique, describing @api access rights, such as admin/anyone

Example:

Defines 200 the return result of a

/* * JS * @apiDefine code_200 * @apiSuccess (reponse) {number} CODE * @apiSuccess (reponse) {JSON} [data= ' "" " ] If there is data back * @apiSuccessExample {JSON} Response Example *   http/1.1 OK *   {*     "code": $, *     "data": "" *   */

Defines 500 the return result of a

/* * * @apiDefine code_500 * @apiSuccess (Response) {number} CODE @apiSuccess (Response) {string} [message] ] Error description * @apiSuccessExample {JSON} Response Example *   http/1.1 Internal Server Error *   {*< c13/> "Code": * "     message": "XXX" * *   /

Defining interfaces

/** * @apiDefine data * @apiParam (data) {string} [FirstName] Optional FirstName of the User. * @apiParam (data) {str ING} lastname Mandatory lastname. * @apiParam (data) {string} country= "cn" Mandatory with default value "DE". * @apiParam (data) {number} [age=18] Optional age with default 18. *//** * @api {POST GET}/api/test/hello[/:id]/api/test/hello[/:id] * @apiName Test API * @apiGroup Hello World * @apiVers Ion 1.0.0 * @apiDescription just a test * @apiPermission anyone * @apiSampleRequesthttp://test.github.com* * @apiParam {number} [ID] any ID * @apiParam {JSON} data Object * @apiUse Data * * @apiParamExample {JSON} Request       Example * POST/API/TEST/HELLO/1 * {* "data": {* "FirstName": "Test", * "LastName": "Sails", * "Country": "CN" *} *} * * @apiUse code_200 * @apiUse code_500*/

After the document is finally generated, the results are as follows

Wen/xun (author of Jane's book)
Original link: http://www.jianshu.com/p/bb5a4f5e588a
Copyright belongs to the author, please contact the author to obtain authorization, and Mark "book author".

Web API Document Generation tool Apidoc