APIDOC

Inline Docmentation for RESTful web APIs

官網(wǎng)地址:http://apidocjs.com/#getting-started

apiDoc通過源代碼里面的API注解生成一份文檔

/** 
* @api {get} /user/:id Request User information 
* @apiName GetUser 
* @apiGroup User 
* 
* @apiParam {Number} id Users unique ID. 
* 
* @apiSuccess {String} firstname Firstname of the User. 
* @apiSuccess {String} lastname Lastname of the User. 
*/

官方例子: watch Demo output

前言

 文檔中所有的例子都使用Javadoc風(fēng)格(適用于C#,Go,Dart,Java,JavaScript, PHP, TypeScript)

  /** 
    * This is a comment. 
    */

安裝

npm install apidoc -g

運(yùn)行

apidoc -i myproject/ -o mydoc/ -t mytemplate/

通過mytemplate文件夾下的模板文件,把myproject文件夾下的所有文件的注釋內(nèi)容生成api文檔,并放在mydoc文件夾下.

終端命令行

提示幫助

apidoc -h

Grunt 模塊

A separate grunt module is supported, visit github.com/apidoc/grunt-apidocor install via npm:

npm install grunt-apidoc --save-dev

模板

apiDoc 的默認(rèn)模板是使用handlebars, Bootstrap, RequireJS 和 jQuery生成
包含api_data.js 和 api_project.js 的html頁面.

默認(rèn)模板支持, 版本信息 和 版本之間的對比

view default demo

自定義模板

通過使用apiDoc生成的api_data.js和api_project.js,或者使用api_data.json,api_project.json等配置文件自定義模板.
View the source on https://github.com/apidoc/apidoc/tree/master/template

Extend

apiDoc can be extended with your own parameters (if something is not available that you need). Look at lib/parsers/, lib/workers/, and lib/parsers/ directories in the apidoc/apidoc-core project for examples. parser
split the parameter data, worker
processes additional functions with all found data and filter
reduce the data to needed things.
Example usage: apidoc --parse-filters myFilter=pathToMyFilter/myFilter.js

Or fork the whole project and create a pull request to make apiDoc better.

配置

放置在項(xiàng)目根目錄的配置項(xiàng)文件apidoc.json包含了關(guān)于項(xiàng)目的基本信息.例如: 標(biāo)題,簡述, 版本號, 配置項(xiàng)如頭尾設(shè)置.

{
  "name": "example",
  "version": "0.1.0", 
  "description": "apiDoc basic example", 
  "title": "Custom apiDoc browser title", 
  "url" : "https://api.github.com/v1"
}

如果你使用package.json,可以在其中添加一個(gè)選項(xiàng)

{ 
  "name": "example", 
  "version": "0.1.0",
  "description": "apiDoc basic example", 
  "apidoc": 
    {
      "title": "Custom apiDoc browser title", 
      "url" : "https://api.github.com/v1" 
    }
}

Settins for apidoc.json

模板設(shè)置

"template":{
  "forceLanguage":"en", //瀏覽器會根據(jù)本地語言自動(dòng)設(shè)置,不建議配置
  "withCompare":true/false, //默認(rèn)true,比較不同版本的接口
  "withGenerator":true/false, //默認(rèn)true,在footer輸出生成信息,例如創(chuàng)建時(shí)間
  "JQueryAjaxSetup":Object //Set [default values](http://api.jquery.com/jquery.ajaxsetup/) for Ajax requests.
}

Header / Footer

{ 
  "header": { 
    "title": "My own header title", 
    "filename": "header.md" 
  }, 
  "footer": { 
    "title": "My own footer title", 
    "filename": "footer.md" 
  }
}

apiDoc-Params

@api

 @api {method} path [title]

例子:

/**
 * @api {get} /user/:id Users unique ID.
 */

@apiDefine

  @apiDefine name [title] 
  [description]

類似自定義方法
在每個(gè)接口塊里只用使用一次@apiDefine
通過@apiUse導(dǎo)入到接口塊里

例子:

 /**
  * @apiDefine MyError
  * @apiError UserNotFound The <code>id</code> of the User was not found.
  */

/**
  * @apiDefine admin User access only
  * This optional description belong to to the group admin.
  */

  /**
  * @api {get} /user/:id
  * @apiPermission admin
  */