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頁面.
默認模板支持, 版本信息 和 版本之間的對比
自定義模板
通過使用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
*/