Web API 文檔生成工具 apidoc

sushi 發布于2019-08-15 13:47 / 1110人閱讀

摘要：實現接口文檔編寫工作，有很多種方式，例如通過文檔編寫，或者通過進行維護。這里，筆者想分享另一個文檔生成工具。此外，可以支持多種語言，，，，，，。查詢簽收預警策略查詢簽收預警策略平臺類型商家名稱最后，我們在終端輸入命令進行文檔生成。

原文地址：梁桂釗的博客

在服務端開發過程中，我們需要提供一份 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/

生成的頁面，如下所示。

（完）

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

云服務器 GPU云服務器生成API文檔接口文檔生成工具 api文檔工具 api接口文檔工具

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/yun/68309.html

開源的api文檔管理系統

摘要：國外的話國內的國內開源的非常好用的一款文檔管理系統，安裝也非常方便，只需將源代碼放到項目目錄下自動安裝運行即可，不要要注意版本必須大于界面簡潔功能強大的阿里的接口管理工具，開源免費，接口自動化，數據自動生成，自動化測試，企業級管理。在項目中，需要協同開發，所以會寫許多API文檔給其他同事，以前都是寫一個簡單的TXT文本或Word文檔，口口相傳，這種方式比較老土了，所以，需要有個api...

zsirfs 2019-06-27 14:58 評論0 收藏0
ApiDoc + github page 使用

摘要：目前支持的變成語言有，，，等，主流的編成語言都支持。文件時你要生成文檔的目錄，也是最后要使用的目錄。是一項免費的服務，它允許你把你的靜態頁面發布出去共其他用戶通過瀏覽器查看。你的項目在用什么工具書寫api文檔？今天就來給大家推薦下ApiDoc 1. ApiDoc是什么？ ApiDoc可以根據你再代碼里的注釋，來生成api描述文檔，這樣就不用你自己去告訴端的小伙伴該怎么調用你的api了...

Joonas 2019-08-23 13:42 評論0 收藏0
ApiDoc + github page 使用

摘要：目前支持的變成語言有，，，等，主流的編成語言都支持。文件時你要生成文檔的目錄，也是最后要使用的目錄。是一項免費的服務，它允許你把你的靜態頁面發布出去共其他用戶通過瀏覽器查看。你的項目在用什么工具書寫api文檔？今天就來給大家推薦下ApiDoc 1. ApiDoc是什么？ ApiDoc可以根據你再代碼里的注釋，來生成api描述文檔，這樣就不用你自己去告訴端的小伙伴該怎么調用你的api了...

luodongseu 2019-08-02 12:07 評論0 收藏0
ApiDoc + github page 使用

摘要：目前支持的變成語言有，，，等，主流的編成語言都支持。文件時你要生成文檔的目錄，也是最后要使用的目錄。是一項免費的服務，它允許你把你的靜態頁面發布出去共其他用戶通過瀏覽器查看。你的項目在用什么工具書寫api文檔？今天就來給大家推薦下ApiDoc 1. ApiDoc是什么？ ApiDoc可以根據你再代碼里的注釋，來生成api描述文檔，這樣就不用你自己去告訴端的小伙伴該怎么調用你的api了...

ytwman 2019-08-16 13:50 評論0 收藏0