Web API 文件生成工具 apidoc

樑桂釗發表於2018-01-23

原文地址:樑桂釗的部落格

在服務端開發過程中,我們需要提供一份 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 可以非常方便地生成可互動地文件頁面。

Web API 文件生成工具 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/
複製程式碼

生成的頁面,如下所示。

Web API 文件生成工具 apidoc

(完)

更多精彩文章,盡在「服務端思維」微信公眾號!

Web API 文件生成工具 apidoc

相關文章