apiDoc文檔

APIDOC

Inline Docmentation for RESTful web APIs

官網地址: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風格(適用於C#,Go,Dart,Java,JavaScript, PHP, TypeScript)

/** 
    * This is a comment. 
    */

安裝

npm install apidoc -g

運行

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

經過_mytemplate_文件夾下的模板文件,把_myproject_文件夾下的全部文件的註釋內容生成api文檔,並放在_mydoc_文件夾下.

終端命令行

提示幫助

apidoc -h

參數	描述
-f	經過正則篩選哪些文件須要生成文檔的.(默認: .cs .dart .erl .go .java  .js .php .py .rb .ts )
-i	你的項目文件所在位置
-o	輸出文檔的位置
-t	自定義模板的位置

Grunt 模塊

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

npm install grunt-apidoc --save-dev

### 模板

apiDoc 的默認模板是使用_handlebars, Bootstrap, RequireJS_ 和 _jQuery_生成
包含api_data.js 和 api_project.js 的html頁面.

默認模板支持, 版本信息 和 版本之間的對比

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.

配置

放置在項目根目錄的配置項文件apidoc.json包含了關於項目的基本信息.例如: 標題,簡述, 版本號, 配置項如頭尾設置.

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

若是你使用package.json,能夠在其中添加一個選項

{ 
  "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

name	Description
name	項目名稱.若是apidoc.json不存在,apidoc會自動尋找package.json裏面的配置項
version	項目版本號
description	項目介紹
title	瀏覽器標題
url	文檔路徑前綴. 例如:https://api.github/com
sampleUrl	爲測試api,提供的測試地址.詳情見@apiSampleRequest
header	title 導航欄開頭標題, filename 以md形式存儲內容.
footer	title 導航欄結尾標題, filename 以md形式存儲內容.
order	排序api名稱或者組名. 默認:"order": [ "Error", "Define", "PostTitleAndError", "PostError"]

模板設置

"template":{
  "forceLanguage":"en", //瀏覽器會根據本地語言自動設置,不建議配置
  "withCompare":true/false, //默認true,比較不一樣版本的接口
  "withGenerator":true/false, //默認true,在footer輸出生成信息,例如建立時間
  "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]

Name	Description
method	請求方式 DELETE,GET,POST,PUT,...
path	接口路徑
title	可選, 簡單說明

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

@apiDefine

@apiDefine name [title] 
  [description]

相似自定義方法
在每一個接口塊裏只用使用一次@apiDefine
經過@apiUse導入到接口塊裏

Name	Description
name	惟一值,同一個name值能夠在不一樣的@apiVersion中定義
title	可選, 小標題,僅能在@apiPermission和@apiParam(name)等方法中使用
description	可選,方法的詳細說明不能與name同行,須要新起一行,能夠換行.只能使用在@apiPermission中

例子:

/**
  * @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
  */