歡迎光臨
每天分享高質量文章

Web API 文件生成工具 apidoc

點擊上方“芋道原始碼”,選擇“置頂公眾號”

技術文章第一時間送達!

原始碼精品專欄

 


摘要: 原文可閱讀 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 篇++

原始碼不易↓↓↓

點贊支持老艿艿↓↓

赞(0)

分享創造快樂