apidoc 使用說明

安裝環境

安裝nodejs和npm
進入官網 https://nodejs.org/en/ 下載首頁推薦的版本就可以

安裝完成後

node -v
v8.12.0

說明安裝成功,安裝nodejs的同時，一併會把npm也替我們安裝好，同樣使用cmd查看npm版本

npm -v
v6.4.1

安裝完成~

安裝apidoc
使用npm進行安裝

npm install apidoc -g

使用apidoc -h
可以查看幫助 說明安裝成功

開始使用

使用apidoc (PHP項目爲例)
新建一個項目或者在老項目根目錄創建 apidoc.json 文件

apidoc.json

{
  "name": "appleFarm", //文檔項目名
  "title": "appleFarmAPI", //html標題
  "description":"appleFarmAPI接口文檔", //文檔描述
  "url" : "https: //xxx.com",//公共接口地址
  "version": "0.1.0" //文檔版本
}

創建src目錄,新建 test.php 文件
添加apidoc註釋

test.php

class Home {
        /**
         * 定義一個變量 用於apiGroup 因爲不支持直接輸入中文
         * @apiDefine test 測試
         */
        
        /**
         * @api {post} /Index/getVip 獲取vip列表   頁面加載時自動獲取
         * @apiName GetUser
         * @apiGroup test
         *
         * @apiParam {string} req1 請求值
         *
         * @apiSuccess {String} res1 返回值1
         * @apiSuccessExample Success-Response:
         * {
         * 　　res1:"test"
         * }
         */
        public function test(){
        }
}

保存完畢之後 我們使用apidoc 命令進行生成文檔(項目根路徑下執行,也就是有apidoc.json文件的路徑)

apidoc -i src/ -o apidoc/
info: Done.

該命令會把所有文件接口註釋全部生成文檔，放到apidoc目錄下，我們進去點開index.html 就可以看到

至此，文檔生成完畢。

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比較特殊，需特別指定。

原文：https://www.jianshu.com/p/d324810d694d