前端和后端注釋文檔生成

前端和后端的 函數(shù)及api 說明文檔生成總結(jié)，持續(xù)更新中 by Qzx

參考網(wǎng)址

• jsDoc - 中文說明
• jsDoc 使用教程
• 后臺接口文檔生成器 - APIDOC官網(wǎng)
• apiDoc - 中文說明

apiDoc的使用教程

一、安裝

# 全局安裝
npm install apidoc -g   
# 查看是否安裝成功,顯示命令行參數(shù)
apidoc -h 

二、apidoc 常用命令說明

三、具體使用

1. 在項目文件夾新建apidoc.json;

2. 在項目目錄運行：

   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）

項目根目錄下的 apidoc.json 可配置項包含有關(guān)項目的常用信息，如 標(biāo)題，簡短描述、版本和配置選項，如頁眉/頁腳設(shè)置或模板特定選項。

• 基本配置方式（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文件的項目中配置(添加"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	項目名稱，若不存在該字段，則會嘗試取 package.json 里面的name值
  version	項目版本號，不存在則讀取 package.json 里面對于的值
  description	項目描述 ，不存在同上
  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.
      */
    ```
  
  

六、示例代碼下載

apiDocDemo示例代碼

七、demo示例效果圖

1532659983362.jpg

1532660016333.jpg

jsDoc的使用教程

一、安裝

# 全局安裝方式
npm install -g jsdoc
# 查看安裝是否成功
jsdoc -v
# 基本使用方式
jsdoc demo.js

二、jsdoc 常用命令說明

三、具體使用

• 命令行新建一個項目

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 + 文件夾路徑