apidoc學習（接口文檔定義取代word）

apidoc的安裝，參考：https://blog.csdn.net/qq_36386771/article/details/82149848

生產文檔，需要先編寫一個apidoc.json對接口文檔進行基本說明，在編寫一些接口定義文檔（采用js），然后運行命令，生成對於的html網頁

demo案例：目錄結構：

xxxx/apidoc_demo/apidoc.json   接口文檔的總說明
xxxx/apidoc_dem/myapp/demo.js  接口文檔具體接口的定義
xxxx/apidoc_dem/apidoc/  用於存放生成的html文件
在xxxx/apidoc_demo/目錄下執行命令 >> apidoc -i myapp/ -o apidoc/

新建apidoc.json

{
  "name": "p1app_v2",
  "description": "P1APP二期的接口文檔",
  "version": "0.0.1",
  "title": "p1app_v2_doc",
  "url": "https://localhost:8010/p1app_v2"
}

新建一個demo.js

    /**
     * @apiDefine Index 首頁
     */

        /**
         * @api {post} /Index/getVip 獲取vip列表   頁面加載時自動獲取
         * @apiName getVip
         * @apiGroup Index
         * @apiParam {string} req1 請求值
         * @apiSuccess (200) {Object[]} profiles List of user profiles.
 	 * @apiSuccess (200) {Number}   profiles.age   Users age.
 	 * @apiSuccess (200) {String}   profiles.image Avatar-Image.
 	 * @apiSuccess (201) {String}   failed Avatar-Image.
         * @apiSuccessExample {json} Success-Response:
         * {
         * 　　res1:"test"
         * }
         */

        /**
         * @api {get} /Index/getWeather 獲取指定日期的逐小時氣象數據信息
         * @apiName getWeather
         * @apiGroup Index
         * @apiDescription 根據傳遞的行政區編碼，獲取所在城市的信息，得到城市對應的氣象數據。
         * @apiParam {String} [date] 日期，格式yyyy-MM-dd,不傳，默認為當日
         * @apiParam {String} region_code 行政區編碼，如"500244"
         * @apiParam {String="hour","day","week","month","year"} data_type 數據類型
         * @apiParam {Number=10,20} num 記錄最大返回條數
         * @apiParam {String{5...10}} strlen 字符串長度限制
         * @apiParam {Number{5-10}} num_range 數字范圍
         * @apiParam {String{5-10}} str_range 字符串范圍
         * @apiVersion 0.0.1
         * @apiSuccess {JsonObject} result JsonObject對象
         * @apiSuccessExample Success-Response:
{
    "code": 0,
    "msg": "success",
    "data":[
      {
        "date": "2019-05-30 01",
        "humidity": 0.97
      },    
      {
        "date": "2019-05-30 02",
        "humidity": 0.98
      }
    ]
}
         */

效果圖如下：

 

apidoc的注解說明：

@api {get} /users/:user_id Request User Information
最主要的參數，”{get}”定義了HTTP請求是GET，API地址是”/users/:user_id”，文檔中API的名稱是”Request User Information”。

@apiVersion 0.1.0
API的版本號，默認顯示在API名稱的右方。該參數可用來在不同的版本之間做比較，后面會介紹。

@apiName GetUser
API名稱，不影響文檔。

@apiGroup User
API分組名，文檔內容中和菜單欄中同一組的API會在一同顯示，方便閱讀。

@apiPermission admin
API的訪問權限，文檔中默認會API地址下面顯示。沒有權限要求的話，此項可以省略。

@apiDescription API to get the user information.
API的詳細描述，默認顯示在API名稱的下方。

@apiExample Example usage:
API調用示例，該參數的下一行就是示例的內容，直到有空行結束。可以定義多個@apiExample，默認在文檔中會以標簽形式列出，標簽名就是”Example usage:”。

@apiParam {Number} user_id The user’s unique ID.
API參數字段介紹，”{Number}”定義了字段類型，”user_id”是字段名稱，后面則是字段描述。可以定義多個@apiParam字段。

@apiSuccess {String} name Name of the User.
API成功后返回的字段，如同@apiParam，”{String}”定義了字段類型，”name”是返回字段名稱，后面則是字段描述。可以定義多個@apiSuccess字段。

@apiSuccessExample {json} Success-Response:
顯示一個API成功返回后Response響應的示例，”{json}”代表響應體是JSON類型。該參數的下行就是響應體內容，直到有空行結束。可以定義多個@apiSuccessExample，默認在文檔中會以標簽形式列出，標簽名就是”Success-Response:”。

@apiError UserNotFound User was not found.
API發生錯誤后的返回，”UserNotFound”是錯誤名稱，后面則是錯誤描述。可以定義多個錯誤返回。

@apiErrorExample {json} Error-Response:
顯示一個API錯誤返回后Response響應的示例，”{json}”代表響應體是JSON類型。該參數的下行就是響應體內容，直到有空行結束。可以定義多個@apiErrorExample，默認在文檔中會以標簽形式列出，標簽名就是”Error-Response:”。

@apiSampleRequest http://localhost:5000/users/:user_id
文檔提供的API Sample測試的地址。其實在”apidoc.json”中配過”sampleUrl”項后，此參數即可省去，除非這個API的測試URL比較特殊，需特別指定。

 

使用js編寫，這些注解都寫在注釋中，上面的內容引用自：https://www.jianshu.com/p/d324810d694d

參數定義說明：參考https://blog.csdn.net/qq_14824885/article/details/87793476#apiParam_251

apidoc使用中文說明：https://blog.csdn.net/qq_14824885/article/details/87793476

apidoc使用英文說明（官方文檔）：http://apidocjs.com/

針對版本變更以及對比，待繼續學習.......