Web API documentation generation tool apidoc installation and use

 

apidoc can generate web api documents based on code comments, and supports most mainstream languages, such as java javascript php coffeescript erlang perl python ruby ​​go.... Relatively speaking, web interface comments are more convenient to maintain, and there is no need to maintain an additional document.

 

apidoc generates static html web page documents from comments, and supports not only the project version number, but also the api version number.

 

Install

Homepage: http://apidocjs.com

github: https://github.com/apidoc/apidoc

You can use npm install apidoc -g to install, currently 0.12.x/4.0 can be used.

 

 

apidoc supports Grunt, homepage https://github.com/apidoc/grunt-apidoc

 

 

1. You need to install the nodejs environment, you can go to the official website to download http://nodejs.cn/download/

2 (optional). Modify the npm global directory under cmd

npm config set prefix "D:\www\nodejs"

 3. Install apidoc in the global directory, command under cmd

npm install apidoc -g

4 (Optional). Set the environment variable to set the path D:\www\nodejs to the path, and set path=1111 under cmd to clear the cache, so there is no need to restart

 

use

Create an apidoc.json file under the project , example

 

{
  "name" : "Integrated Platform Interface",
  "version": "1.0.0",
  "title": "Integrated Platform Interface",
  "url" : "http://center.ys.test",
  "sampleUrl":  "http://center.ys.test",
  "description": "Comprehensive Platform Interface Documentation",
  "template": {
    "forceLanguage" : "zh_cn",
    "withCompare": true,
    "withGenerator": true
  },
  "header": {
    "title": "Comprehensive Platform Description",
    "filename": "header.md"
  },
  "order" : [

    "home",
    "homeApps",

    "user",
    "userList",
    "userInfo",
    "userDelete",

    ""

  ]
}

 If put in package.json, the same fields can be directly defined in package.json, and additional fields are put under apidoc

 

 

{
  "name": "mysails",
  "private": true,
  "version": "1.0.0",
  "description": "xun's test project",
  "apidoc": {
    "title": "mysails"
  },
  ...
}

 

 

Code comments indicate that apidoc supports the following keywords  

@api {method} path [title]
  Only comment blocks marked with @api will generate documentation after parsing, and title will be parsed as a small menu under the navigation menu (@apiGroup)
  method can have spaces, such as {POST GET}
@apiGroup name
  Group name, parsed as navbar menu
@apiName name
  Interface name, under the same @apiGroup, @api with the same name is distinguished by @apiVersion, otherwise @api will overwrite the @api defined earlier
@apiDescription text
  Interface description, support html syntax
@apiVersion verison
  Interface version, in the form of major.minor.patch

@apiIgnore [hint]
  apidoc ignores interfaces marked with @apiIgnore, hint is description
@apiSampleRequest url
  The interface test address is used for testing. When sending a request, the @api method must be one of POST/GET, etc.

@apiDefine name [title] [description]
  Define a comment block (excluding @api), which can be introduced with @apiUse
  @apiUse cannot be used inside @apiDefine
@apiUse name
  Introduce an @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]
  The usage is basically similar, describing the request parameters, headers, response errors and successes respectively
  group represents the grouping of parameters, type represents the type (no spaces), and default values ​​can be defined for the input parameters (no spaces)
@apiParamExample [{type}] [title] example
@apiHeaderExample [{type}] [title] example
@apiErrorExample [{type}] [title] example
@apiSuccessExample [{type}] [title] example
  The usage is exactly the same, but type represents the language type of example
  The example will be parsed as it is written, so it is best to pay attention to formatting when writing, (many editors have column mode, you can use column mode to quickly add * to the code)

@apiPermission name
  The name must be unique and describe the access rights of @api, such as admin/anyone

  Example

/**
     * @apiDefine sendError
     * @apiError {Number} status Response status 0 means failure
     * @apiError {String} request request address
     * @apiError {String} error error description
     * @apiError {Number} error_code Error code
     */

    /**
     * @apiDefine sendSuccess
     * @apiSuccess {String} status Response status 1 indicates success
     * @apiSuccess {String} request path
     * @apiSuccess {Aarray[]} data data
     */

    /**
     * @apiDefine defaultParam
     * @apiParam {String=web,server} platform web access fill in web server access fill in server
     * @apiParam {String=json,xml} [format=json] Return format default json
     */

    /**
     * @api {get} /home/api/apps Get the list of user apps
     * @apiVersion 1.0.0
     * @apiGroup home
     * @apiName homeApps
     * @apiDescription
     * Get the apps interface
     * You need to log in to access
     *
     * @apiUse defaultParam
     *
     * @apiUse sendSuccess
     * @apiSuccess {Aarray[]} data data
     * @apiSuccess {Number} data.id application id
     * @apiSuccess {String} data.name English name
     * @apiSuccess {String} data.title Chinese name
     * @apiSuccess {String} data.description description
     * @apiSuccess {Number} data.status status
     * @apiSuccess {String} data.author author
     * @apiSuccess {String} data.version version number
     * @apiSuccess {Number} data.create_time creation timestamp
     * @apiSuccess {Number} data.update_time update timestamp
     * @apiSuccess {Number} data.auth Visible permissions 0 available for all 1 available for specified users 2 available only for super system administrators - 1 available for guests
     * @apiSuccess {String} data.host_url domain name
     * @apiSuccess {String} data.home_url entry address
     * @apiSuccess {String} data.icon_url icon address
     *
     * @apiSuccessExample {json} return example
    {"status":1,"request":"\/home\/api\/apps?platform=web","data":[{"id":2,"name":"department","title":"部门管理","description":"部门","status":1,"config":null,"author":null,"version":null,"create_time":1490063104,"update_time":1490063104,"auth":0,"type":1,"host_url":null,"home_url":"http:\/\/center.ys.test\/department\/department\/index.html","icon_url":"\/data\/apps\/department\/icon.png"},{"id":3,"name":"apps","title":"应用管理","description":"应用管理","status":1,"config":null,"author":null,"version":null,"create_time":1490063104,"update_time":1490063104,"auth":2,"type":1,"host_url":null,"home_url":"http:\/\/center.ys.test\/apps\/apps\/index.html","icon_url":"\/data\/apps\/apps\/icon.png"}]}
     * @apiUse sendError
     * @apiErrorExample {json} return example
    {"status":0,"request":"\/home\/api\/apps?platform=web","error":"您还没有登录过！","error_code":"10001"}
     */
    /**
     * This paragraph has nothing to do with apidoc
     * @apiDefine is used to define and then call via @apiUse sendError 
     */

  Finally, the document is generated by the command, as follows, the environment variable has been set, and apidoc can be directly typed

apidoc -i D:\www\php\ysos\ys_center\application -o D:\www\php\ysos\ys_center\public\apidoc

 -i input directory apidoc.json storage directory -o output directory