前端和后端注釋文檔生成
前端和后端的 函數(shù)及api 說明文檔生成總結(jié)曙搬，持續(xù)更新中 by Qzx
參考網(wǎng)址
apiDoc的使用教程
一、安裝
# 全局安裝
npm install apidoc -g
# 查看是否安裝成功,顯示命令行參數(shù)
apidoc -h
二、apidoc 常用命令說明
| 指令簡寫 | 指令全稱 | 說明 |
|---|---|---|
| -f | --file-filters | 過濾器僚纷，指定應(yīng)該解析的文件類型梢睛，后綴 （可以使用多個-f）逛裤。默認(rèn).cs .dart .erl .go .java .js .php .py .rb .ts。示例（僅解析.js和.ts文件）：apidoc -f ".*\.js" -f ".*\\.ts" |
| -e | --exclude-filters | 過濾器用于選擇不應(yīng)該解析的文件 |
| -i | --input | 指定輸入的源目錄名狈蚤，項(xiàng)目文件的位置，默認(rèn)為 ./ 例：apidoc -i myapp/ |
| -o | --output | 指定輸出的目錄文件名划纽，放置生成文檔的位置脆侮，默認(rèn)為 ./doc/，例：apidoc -o apidoc/ |
| -t | --template | 指定要用的外部模板的路徑勇劣，可以創(chuàng)建和使用自己的模板靖避，默認(rèn)使用全局的 node_modules/apidoc/template/ ，例：apidoc -t mytemplate/ |
| -c | --config | 指定配置文件的路徑 apidoc.json ./ |
| -h | --help | 顯示詳細(xì)的幫助說明 |
| --debug | --debug | 顯示調(diào)試的信息比默，默認(rèn)為 false |
三幻捏、具體使用
在項(xiàng)目文件夾新建apidoc.json;
-
在項(xiàng)目目錄運(yùn)行：
apidoc -i myapp/ -o apidoc/ -t mytemplate/ # 簡寫指令 apidoc
說明：上面的指令可以直接簡寫為 apidoc，沒有任何參數(shù)時命咐，默認(rèn)從當(dāng)前目錄(包括子目錄)下格式為(.cs .dart .erl .go .java .js .php .py .rb .ts) 的所有文件生成文檔并將輸出寫入 ./doc/篡九。
四、基本配置（apidoc.json）
項(xiàng)目根目錄下的 apidoc.json 可配置項(xiàng)包含有關(guān)項(xiàng)目的常用信息醋奠，如 標(biāo)題榛臼，簡短描述、版本和配置選項(xiàng)窜司，如頁眉/頁腳設(shè)置或模板特定選項(xiàng)沛善。
-
基本配置方式（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文件的項(xiàng)目中配置(添加"apidoc":{}參數(shù))
{ "name": "example", "version": "0.1.0", "description": "apiDoc basic example", "apidoc": { "title": "Custom apiDoc browser title", "url" : "https://api.github.com/v1" } } -
添加額外的 Header 和 Footer (不常用，在apidoc.json添加header和footer參數(shù))
{ "header": { "title": "My own header title", "filename": "header.md" }, "footer": { "title": "My own footer title", "filename": "footer.md" } } -
配置參數(shù)的詳細(xì)說明(apidoc.json)
參數(shù)名 描述 name 項(xiàng)目名稱塞祈，若不存在該字段金刁，則會嘗試取 package.json 里面的name值 version 項(xiàng)目版本號，不存在則讀取 package.json 里面對于的值 description 項(xiàng)目描述 织咧，不存在同上 title 瀏覽器標(biāo)題文本 url api路徑的前綴胀葱，適合同一域下的接口漠秋，例：https://api.github.com/v1 sampleUrl 測試樣例的url, 具體請參考 @apiSampleRequest header 添加自定義的頂部描述 {title: '', filename: ''} title 頂部的標(biāo)題 filename 頂部具體的展現(xiàn)內(nèi)容 footer 添加自定義的尾部描述 {title: '', filename: ''} title 尾部的標(biāo)題 filename 尾部具體的展現(xiàn)內(nèi)容 order 用于定義輸出的api-names/group-name列表排序笙蒙。最后自動顯示未定義的名稱。"order": ["Error","Define","PostTitleAndError","PostError"]
五庆锦、apiDoc 常用api說明
常用api：
@api,@apiName,@apiGroup,@apiVersion,@apiDescription,@apiParam,@apiSuccess,@apiSuccessExample,@apiDefine,@apiError,@apiIgnore-
基本例子(demo.js)
/** * @api {get} /user/:id Request User information * @apiVersion 0.1.0 * @apiName GetUser * @apiGroup User * * @apiParam {Number} id Users unique ID. * * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. * * @apiSuccessExample Success-Response: * HTTP/1.1 200 OK * { * "firstname": "John", * "lastname": "Doe" * } * * @apiError UserNotFound The id of the User was not found. * * @apiErrorExample Error-Response: * HTTP/1.1 404 Not Found * { * "error": "UserNotFound" * } */說明：文檔塊以
/**和*/結(jié)尾捅位，其中@api為必須字段，格式同例子：@api + {請求類型} + 接口路徑 + 接口描述搂抒，在生成的時候沒有@api 的文檔塊會被忽略艇搀。@apiName和@apiGroup,在版本迭代時應(yīng)保持一致，其他字段為可選求晶。 -
@api (必須字段焰雕，沒有會被忽略)
@api {method} path [title]例：@api {get} /user/:id Users unique ID.
-
@apiParam
@apiParam [(group)] [{type}] [field=defaultValue] [description]示例：
/** * @api {get} /user/:id * @apiParam {Number} id Users unique ID. */ /** * @api {post} /user/ * @apiParam {String} [firstname] Optional Firstname of the User. * @apiParam {String} lastname Mandatory Lastname. * @apiParam {String} country="DE" Mandatory with default value "DE". * @apiParam {Number} [age=18] Optional Age with default 18. * * @apiParam (Login) {String} pass Only logged in users can post this. * In generated documentation a separate * "Login" Block will be generated. */說明：1. 帶括號的Fieldname將Variable定義為可選。2. =defaultValue 參數(shù)默認(rèn)值芳杏。
-
@apiSuccess
@apiSuccess [(group)] [{type}] field [description]示例：
/** * @api {get} /user/:id * @apiSuccess {String} firstname Firstname of the User. * @apiSuccess {String} lastname Lastname of the User. */ /** * @api {get} /user/:id * @apiSuccess (200) {String} firstname Firstname of the User. * @apiSuccess (200) {String} lastname Lastname of the User. */ /** * @api {get} /user/:id * @apiSuccess {Boolean} active Specify if the account is active. * @apiSuccess {Object} profile User profile information. * @apiSuccess {Number} profile.age Users age. * @apiSuccess {String} profile.image Avatar-Image. */ ```
六矩屁、示例代碼下載
七辟宗、demo示例效果圖
1532659983362.jpg
1532660016333.jpg
jsDoc的使用教程
一、安裝
# 全局安裝方式
npm install -g jsdoc
# 查看安裝是否成功
jsdoc -v
# 基本使用方式
jsdoc demo.js
二吝秕、jsdoc 常用命令說明
| 指令簡寫 | 指令全稱 | 說明 |
|---|---|---|
| -f | --file-filters | 過濾器泊脐，指定應(yīng)該解析的文件類型，后綴 （可以使用多個-f）烁峭。默認(rèn).cs .dart .erl .go .java .js .php .py .rb .ts容客。示例（僅解析.js和.ts文件）：apidoc -f ".*\.js" -f ".*\\.ts" |
| -e | --exclude-filters | 過濾器用于選擇不應(yīng)該解析的文件 |
三、具體使用
- 命令行新建一個項(xiàng)目
mkdir jsDocDemo
cd jsDocDemo
npm init -y
- 新建一個demo.js,代碼示例如下:
/**
* Book類约郁，代表一個書本.
* @constructor
* @param {string} title - 書本的標(biāo)題.
* @param {string} author - 書本的作者.
*/
function Book(title, author) {
this.title=title;
this.author=author;
}
Book.prototype={
/**
* 獲取書本的標(biāo)題
* @returns {string|*}
*/
getTitle:function(){
return this.title;
},
/**
* 設(shè)置書本的頁數(shù)
* @param pageNum {number} 頁數(shù)
*/
setPageNum:function(pageNum){
this.pageNum=pageNum;
}
};
- 命令行編譯文件
jsdoc demo.js
注： 默認(rèn)生成在 out 目錄下缩挑，更換目錄可使用 -d + 文件夾路徑
