知識星球點選上方“芋道原始碼”，選擇“置頂公眾號”
技術文章第一時間送達！
原始碼精品專欄
摘要: 原文可閱讀 http://www.iocoder.cn/Fight/web-api-doc 「老梁」歡迎轉載，保留摘要，謝謝！
-
開始入門
-
程式碼註釋
-
完整的案例
在服務端開發過程中，我們需要提供一份 API 介面檔案給 Web 端和移動端使用。實現 API 介面檔案編寫工作，有很多種方式，例如透過 Word 檔案編寫，或者透過 MediaWiki 進行維護。此外，還有比較流行的方式是利用 Swagger 自動化生成檔案。這裡，筆者想分享另一個 Web API 檔案生成工具 apidoc。
apidoc 是透過原始碼中的註釋來生成 Web API 檔案。因此，apidoc 對現有程式碼可以做到無侵入性。此外，apidoc 可以支援多種語言 C#, Go, Dart, Java, JavaScript, PHP, TypeScript (all DocStyle capable languages)，CoffeeScript，Erlang，Perl，Python，Ruby，Lua。透過 apidoc 可以非常方便地生成可互動地檔案頁面。
開始入門
首先，我們需要 node.js 的支援。在搭建好 node.js 環境後，透過終端輸入 npm 命名進行安裝。
npm install apidoc -g
接著，我們還需要新增 apidoc.json 檔案到專案工程的根目錄下。
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
這裡，筆者主要演示 Java 註釋如何和 apidoc 結合使用。現在，我們先來看一個案例。
/**
* @api {GET} logistics/policys 查詢簽收預警策略
* @apiDescription 查詢簽收預警策略
* @apiGroup QUERY
* @apiName logistics/policys
* @apiParam {Integer} edition 平臺型別
* @apiParam {String} tenantCode 商家名稱
* @apiPermission LOGISTICS_POCILY
*/
最後，我們在終端輸入 apidoc 命令進行檔案生成。這裡，我們用自己的專案工程的根目錄替代 myapp/,用需要生成檔案的地址替代 apidoc/。
apidoc -i myapp/ -o apidoc/
例如，筆者的配置是這樣的。
apidoc -i /Users/lianggzone/Documents/dev-space/git-repo -o /Users/lianggzone/Documents/dev-space/apidoc/
程式碼註釋
@api
@api 標簽是必填的，只有使用 @api 標簽的註釋塊才會被解析生成檔案內容。格式如下：
@api {method} path [title]
這裡，有必要對引數內容進行講解。
| 引數名 | 描述 |
|---|---|
| method | 請求方法, 如 POST，GET，POST，PUT，DELETE 等。 |
| path | 請求路徑。 |
| title【選填】 | 簡單的描述 |
@apiDescription
@apiDescription 對 API 介面進行描述。格式如下：
@apiDescription text
@apiGroup
@apiGroup 表示分組名稱，它會被解析成一級導航欄選單。格式如下：
@apiGroup name
@apiName
@apiName 表示介面名稱。註意的是，在同一個 @apiGroup 下，名稱相同的 @api 透過 @apiVersion 區分，否者後面 @api 會改寫前面定義的 @api。格式如下：
@apiName name
@apiVersion
@apiVersion 表示介面的版本，和 @apiName 一起使用。格式如下：
@apiVersion version
@apiParam
@apiParam 定義 API 介面需要的請求引數。格式如下：
@apiParam [(group)] [{type}] [field=defaultValue] [description]
這裡，有必要對引數內容進行講解。
| 引數名 | 描述 |
|---|---|
| (group)【選填】 | 引數進行分組 |
| {type}【選填】 | 引數型別，包括{Boolean}, {Number}, {String}, {Object}, {String[]}， (array of strings), … |
| {type{size}}【選填】 | 可以宣告引數範圍，例如{string{..5}}， {string{2..5}}， {number{100-999}} |
| {type=allowedValues}【選填】 | 可以宣告引數允許的列舉值，例如{string=”small”,”huge”}， {number=1,2,3,99} |
| field | 引數名稱 |
| [field] | 宣告該引數可選 |
| =defaultValue【選填】 | 宣告該引數預設值 |
| description【選填】 | 宣告該引數描述 |
類似的用法，還有 @apiHeader 定義 API 介面需要的請求頭，@apiSuccess 定義 API 介面需要的響應成功，@apiError 定義了 API 介面需要的響應錯誤。
這裡，我們看一個案例。
/**
* @apiParam {Integer} edition=1 平臺型別
* @apiParam {String} [tenantCode] 商家名稱
*/
此外，還有 @apiParamExample，@apiHeaderExample， @apiErrorExample，@apiSuccessExample 可以用來在檔案中提供相關示例。
@apiPermission
@apiPermission 定義 API 介面需要的許可權點。格式如下：
@apiPermission name
此外，還有一些特別的註解。例如 @apiDeprecated 表示這個 API 介面已經廢棄，@apiIgnore 表示忽略這個介面的解析。關於更多的使用細節，可以閱讀官方檔案：http://apidocjs.com/#demo
完整的案例
最後，我們用官方的案例，講解下一個完整的配置。
首先，配置 apidoc.json，內容如下：
{
"name": "example",
"version": "0.1.0",
"description": "A basic apiDoc example"
}
接著，我們配置相關的 Java 原始碼註釋。
/**
* @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.
*
* @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"
* }
*/
然後，執行命名生成檔案。
apidoc -i myapp/ -o apidoc/
生成的頁面，如下所示。
如果你對 Dubbo 感興趣，歡迎加入我的知識星球一起交流。
目前在知識星球（https://t.zsxq.com/2VbiaEu）更新瞭如下 Dubbo 原始碼解析如下：
01. 除錯環境搭建
02. 專案結構一覽
03. 配置 Configuration
04. 核心流程一覽
05. 拓展機制 SPI
06. 執行緒池
07. 服務暴露 Export
08. 服務取用 Refer
09. 註冊中心 Registry
10. 動態編譯 Compile
11. 動態代理 Proxy
12. 服務呼叫 Invoke
13. 呼叫特性
14. 過濾器 Filter
15. NIO 伺服器
16. P2P 伺服器
17. HTTP 伺服器
18. 序列化 Serialization
19. 叢集容錯 Cluster
20. 優雅停機
21. 日誌適配
22. 狀態檢查
23. 監控中心 Monitor
24. 管理中心 Admin
25. 運維命令 QOS
26. 鏈路追蹤 Tracing
…
一共 60 篇++
原始碼不易↓↓↓↓↓
點贊支援老艿艿↓↓