資訊專欄INFORMATION COLUMN
摘要：實(shí)現(xiàn)接口文檔編寫工作，有很多種方式，例如通過文檔編寫，或者通過進(jìn)行維護(hù)。這里，筆者想分享另一個(gè)文檔生成工具。此外，可以支持多種語言，，，，，，。查詢簽收預(yù)警策略查詢簽收預(yù)警策略平臺(tái)類型商家名稱最后，我們在終端輸入命令進(jìn)行文檔生成。
原文地址：梁桂釗的博客
在服務(wù)端開發(fā)過程中，我們需要提供一份 API 接口文檔給 Web 端和移動(dòng)端使用。實(shí)現(xiàn) API 接口文檔編寫工作，有很多種方式，例如通過 Word 文檔編寫，或者通過 MediaWiki 進(jìn)行維護(hù)。此外，還有比較流行的方式是利用 Swagger 自動(dòng)化生成文檔。這里，筆者想分享另一個(gè) Web API 文檔生成工具 apidoc。
apidoc 是通過源碼中的注釋來生成 Web API 文檔。因此，apidoc 對(duì)現(xiàn)有代碼可以做到無侵入性。此外，apidoc 可以支持多種語言 C#, Go, Dart, Java, JavaScript, PHP, TypeScript (all DocStyle capable languages)，CoffeeScript，Erlang，Perl，Python，Ruby，Lua。通過 apidoc 可以非常方便地生成可交互地文檔頁面。
開始入門首先，我們需要 node.js 的支持。在搭建好 node.js 環(huán)境后，通過終端輸入 npm 命名進(jìn)行安裝。
npm install apidoc -g
接著，我們還需要添加 apidoc.json 文件到項(xiàng)目工程的根目錄下。
{
"name": "example",
"version": "0.1.0",
"description": "apiDoc basic example",
"title": "Custom apiDoc browser title",
"url" : "https://api.github.com/v1"
}
這里，筆者主要演示 Java 注釋如何和 apidoc 結(jié)合使用?，F(xiàn)在，我們先來看一個(gè)案例。
/**
* @api {GET} logistics/policys 查詢簽收預(yù)警策略
* @apiDescription 查詢簽收預(yù)警策略
* @apiGroup QUERY
* @apiName logistics/policys
* @apiParam {Integer} edition 平臺(tái)類型
* @apiParam {String} tenantCode 商家名稱
* @apiPermission LOGISTICS_POCILY
*/
最后，我們在終端輸入 apidoc 命令進(jìn)行文檔生成。這里，我們用自己的項(xiàng)目工程的根目錄替代 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 標(biāo)簽是必填的，只有使用 @api 標(biāo)簽的注釋塊才會(huì)被解析生成文檔內(nèi)容。格式如下：
@api {method} path [title]
這里，有必要對(duì)參數(shù)內(nèi)容進(jìn)行講解。
| 參數(shù)名 | 描述 |
|---|---|
| method | 請(qǐng)求方法, 如 POST，GET，POST，PUT，DELETE 等。 |
| path | 請(qǐng)求路徑。 |
| title【選填】 | 簡單的描述 |
@apiDescription 對(duì) API 接口進(jìn)行描述。格式如下：
@apiDescription text@apiGroup
@apiGroup 表示分組名稱，它會(huì)被解析成一級(jí)導(dǎo)航欄菜單。格式如下：
@apiGroup name@apiName
@apiName 表示接口名稱。注意的是，在同一個(gè) @apiGroup 下，名稱相同的 @api 通過 @apiVersion 區(qū)分，否者后面 @api 會(huì)覆蓋前面定義的 @api。格式如下：
@apiName name@apiVersion
@apiVersion 表示接口的版本，和 @apiName 一起使用。格式如下：
@apiVersion version@apiParam
@apiParam 定義 API 接口需要的請(qǐng)求參數(shù)。格式如下：
@apiParam [(group)] [{type}] [field=defaultValue] [description]
這里，有必要對(duì)參數(shù)內(nèi)容進(jìn)行講解。
| 參數(shù)名 | 描述 |
|---|---|
| (group)【選填】 | 參數(shù)進(jìn)行分組 |
| {type}【選填】 | 參數(shù)類型，包括{Boolean}, {Number}, {String}, {Object}, {String[]}， (array of strings), ... |
| {type{size}}【選填】 | 可以聲明參數(shù)范圍，例如{string{..5}}， {string{2..5}}， {number{100-999}} |
| {type=allowedValues}【選填】 | 可以聲明參數(shù)允許的枚舉值，例如{string="small","huge"}， {number=1,2,3,99} |
| field | 參數(shù)名稱 |
| [field] | 聲明該參數(shù)可選 |
| =defaultValue【選填】 | 聲明該參數(shù)默認(rèn)值 |
| description【選填】 | 聲明該參數(shù)描述 |
類似的用法，還有 @apiHeader 定義 API 接口需要的請(qǐng)求頭，@apiSuccess 定義 API 接口需要的響應(yīng)成功，@apiError 定義了 API 接口需要的響應(yīng)錯(cuò)誤。
這里，我們看一個(gè)案例。
/**
* @apiParam {Integer} edition=1 平臺(tái)類型
* @apiParam {String} [tenantCode] 商家名稱
*/
此外，還有 @apiParamExample，@apiHeaderExample， @apiErrorExample，@apiSuccessExample 可以用來在文檔中提供相關(guān)示例。
@apiPermission@apiPermission 定義 API 接口需要的權(quán)限點(diǎn)。格式如下：
@apiPermission name
此外，還有一些特別的注解。例如 @apiDeprecated 表示這個(gè) API 接口已經(jīng)廢棄，@apiIgnore 表示忽略這個(gè)接口的解析。關(guān)于更多的使用細(xì)節(jié)，可以閱讀官方文檔：http://apidocjs.com/#demo
完整的案例最后，我們用官方的案例，講解下一個(gè)完整的配置。
首先，配置 apidoc.json，內(nèi)容如下：
{
"name": "example",
"version": "0.1.0",
"description": "A basic apiDoc example"
}
接著，我們配置相關(guān)的 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"
* }
*/
然后，執(zhí)行命名生成文檔。
apidoc -i myapp/ -o apidoc/
生成的頁面，如下所示。
（完）
更多精彩文章，盡在「服務(wù)端思維」微信公眾號(hào)！
文章版權(quán)歸作者所有，未經(jīng)允許請(qǐng)勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。
轉(zhuǎn)載請(qǐng)注明本文地址：http://systransis.cn/yun/68309.html
摘要：國外的話國內(nèi)的國內(nèi)開源的非常好用的一款文檔管理系統(tǒng)，安裝也非常方便，只需將源代碼放到項(xiàng)目目錄下自動(dòng)安裝運(yùn)行即可，不要要注意版本必須大于界面簡潔功能強(qiáng)大的阿里的接口管理工具，開源免費(fèi)，接口自動(dòng)化，數(shù)據(jù)自動(dòng)生成，自動(dòng)化測試，企業(yè)級(jí)管理。 在項(xiàng)目中，需要協(xié)同開發(fā)，所以會(huì)寫許多API文檔給其他同事，以前都是寫一個(gè)簡單的TXT文本或Word文檔，口口相傳，這種方式比較老土了，所以，需要有個(gè)api...
摘要：目前支持的變成語言有，，，等，主流的編成語言都支持。文件時(shí)你要生成文檔的目錄，也是最后要使用的目錄。是一項(xiàng)免費(fèi)的服務(wù)，它允許你把你的靜態(tài)頁面發(fā)布出去共其他用戶通過瀏覽器查看。 你的項(xiàng)目在用什么工具書寫api文檔？今天就來給大家推薦下ApiDoc 1. ApiDoc是什么？ ApiDoc可以根據(jù)你再代碼里的注釋，來生成api描述文檔，這樣就不用你自己去告訴端的小伙伴該怎么調(diào)用你的api了...
摘要：目前支持的變成語言有，，，等，主流的編成語言都支持。文件時(shí)你要生成文檔的目錄，也是最后要使用的目錄。是一項(xiàng)免費(fèi)的服務(wù)，它允許你把你的靜態(tài)頁面發(fā)布出去共其他用戶通過瀏覽器查看。 你的項(xiàng)目在用什么工具書寫api文檔？今天就來給大家推薦下ApiDoc 1. ApiDoc是什么？ ApiDoc可以根據(jù)你再代碼里的注釋，來生成api描述文檔，這樣就不用你自己去告訴端的小伙伴該怎么調(diào)用你的api了...
摘要：目前支持的變成語言有，，，等，主流的編成語言都支持。文件時(shí)你要生成文檔的目錄，也是最后要使用的目錄。是一項(xiàng)免費(fèi)的服務(wù)，它允許你把你的靜態(tài)頁面發(fā)布出去共其他用戶通過瀏覽器查看。 你的項(xiàng)目在用什么工具書寫api文檔？今天就來給大家推薦下ApiDoc 1. ApiDoc是什么？ ApiDoc可以根據(jù)你再代碼里的注釋，來生成api描述文檔，這樣就不用你自己去告訴端的小伙伴該怎么調(diào)用你的api了...
閱讀 2905·2021-11-22 13:54
閱讀 3541·2021-11-16 11:44
閱讀 1381·2021-09-07 10:19
閱讀 1483·2019-08-29 17:30
閱讀 3206·2019-08-29 11:33
閱讀 3554·2019-08-26 12:18
閱讀 2894·2019-08-26 11:53
閱讀 1347·2019-08-26 10:47
