webApi文檔好幫手-apidoc使用教程

本文轉載自查看原文 2017-09-18 14:44 4806 雜項

在開發后台接口的過程中，我們肯定要提供一份api接口文檔給終端app。

目前大多數的app的接口請求應該都是http+json的方式。但是一直苦於做不出份漂亮的api文檔，用word寫，也太丑了。。怎么才能做出一份像騰訊、新浪微博等各種開放api平台那樣漂亮的api文檔呢？找了好久發現了今天的主角-apidoc。

官網地址：http://apidocjs.com

開放API已經成為當下主流平台的一個要素，特別對於社交、電商類的平台開放API更成為了競爭力的一種。開放API文檔的完整性、可閱讀性往往影響着接入方是否能順利地、快速地接入到平台，一份好的、統一的API文檔也是開放平台不可或缺的要素。

apidoc是通過源碼中的注釋來生成API文檔，所以只要識別兼容現今大部分流行語言的注釋方法便達到了兼容語言的效果。

有了它，我們只需要在寫源碼的時候順手寫上一些簡單的注釋，就可以生成出漂亮的文檔了（當然，有同學會問文檔不是先定義的嗎？你把接口的源碼聲明好不就ok啦？或者你寫點其他的語言也行啊。。最簡單的就是學習下javascript，只要學會怎么創建js文件，然后怎么聲明function，給function添加注釋即可，實在寫不了源碼，寫一個簡單的js文件，然后用apidoc生成一下就出文檔了。）。

它可以對API的各種版本等級進行對比。所以無論是前端開發人員還是你都可以追溯API版本的變化。

支持多種語言：C#, Go, Dart, Java, JavaScript, PHP, TypeScript (all DocStyle capable languages)，CoffeeScript，Erlang，Perl，Python，Ruby。

使用步驟：

1.安裝nodejs。去http://www.nodejs.org/下載安裝一個nodejs；

2.安裝apidoc：命令行輸入：npm install apidoc -g 貌似是在線安裝的，稍等一下即可。

3. 准備一個目錄myapp，下面放源碼文件，源碼文件中要按照apidoc的規范寫好注釋。具體規范參見官網，我這里就不翻譯了。

例如我寫java的源碼：

/** 
 * 此接口不要去實現，僅作為輸出api文檔用的 
 * @author xumin 
 * 
 */  
@Deprecated  
public interface ApiDoc {  
    /** 
     *  
     * @api {get} /company/list 獲取公司信息 
     * @apiName 獲取公司列表 
     * @apiGroup All 
     * @apiVersion 0.1.0 
     * @apiDescription 接口詳細描述 
     *  
     * @apiParam {int} pageNum分頁大小  
     *  
     * @apiSuccess {String} code 結果碼 
     * @apiSuccess {String} msg 消息說明 
     * @apiSuccess {Object} data 分頁數據封裝 
     * @apiSuccess {int} data.count 總記錄數 
     * @apiSuccess {Object[]} data.list 分頁數據對象數組 
     * @apiSuccessExample Success-Response: 
     *  HTTP/1.1 200 OK 
     * { 
     * code:0, 
     * msg:'success', 
     * data:{} 
     *  } 
     *   
     *  @apiError All 對應<code>id</code>的用戶沒找到 asdfasdf  
     *  @apiErrorExample {json} Error-Response: 
     *  HTTP/1.1 404 Not Found 
     *  { 
     *   code:1, 
     *   msg:'user not found', 
     *   } 
     *    
     * @param param 
     * @return 
     * @throws Exception 
     */  
    void a();  
}

4. 生成api文檔。

apidoc -i myapp/ -o apidoc/ -t mytemplate/

apidoc是用於存放生成出的文檔文件的目錄

mytemplate是自定義模板文件夾，剛開始用，可以不指定，后面有需要了再研究怎么自定義模板吧。

如果看到“success: Done.”說明生成成功，到 apidoc目錄下打開index.html查看生成的文檔.

大功告成！

apiDoc-Params

結構參數如：

@apiDefine

用於定義可重用的文檔塊。此塊可以包含在正常的api文檔塊中。使用@apiDefine可以更好地組織復雜的文檔，並避免復制循環塊。

定義的塊可以具有所有參數（如@apiParam）， 除了其他定義的塊。

@api

@api {method} path [title]

需要！

沒有該指標，apiDoc解析器忽略文檔塊。

唯一的例外是由@apiDefine定義的文檔塊，它們不需要@api。

用法: @api {get} /user/:id Users unique ID.

名稱	說明
method	請求方式名稱: `DELETE`, `GET`, `POST`, `PUT`, ... 跟多請參考 Wikipedia HTTP-Request_methods
path	請求地址
titleoptional	一個簡短的標題。（用於導航和文章標題）

示例:

/**
 * @api {get} /user/:id
 */

@apiDefine

@apiDefine name [title]
                     [description]

定義要嵌入在@api塊中的文檔塊或者像@apiPermission這樣的api函數。

@apiDefine只能在每個塊中使用一次

通過使用@apiUse將導入一個定義的塊，或者使用名稱標題和描述將被使用。

用法: @apiDefine MyError

名稱	說明
name	塊/值的唯一名稱。可以定義與不同@apiVersion相同的名稱。
titleoptional	一個簡短的標題。只用於@apiPermission或@apiParam（name）等命名函數。
descriptionoptional	詳細說明從下一行開始，可以使用多行。僅用於像@apiPermission這樣的命名函數。

示例:

/**
 * @apiDefine MyError
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */

/**
 * @api {get} /user/:id
 * @apiUse MyError
 */

/**
 * @apiDefine admin User access only
 * This optional description belong to to the group admin.
 */

/**
 * @api {get} /user/:id
 * @apiPermission admin
 */

有關更多詳細信息，請參閱繼承示例。

@apiDeprecated

@apiDeprecated [text]

將API標記為不推薦使用

用法: @apiDeprecated use now (#Group:Name).

名稱	說明
text	多行文本

示例:

/**
 * @apiDeprecated
 */

/**
 * @apiDeprecated use now (#Group:Name).
 *
 * Example: to set a link to the GetDetails method of your group User
 * write (#User:GetDetails)
 */

@apiDescription

@apiDescription text

API方法的詳細描述。

用法: @apiDescription This is the Description.

名稱	說明
text	多線描述文字。

示例:

/**
 * @apiDescription This is the Description.
 * It is multiline capable.
 *
 * Last line of Description.
 */

@apiError

@apiError [(group)] [{type}] field [description]

錯誤返回參數。

用法: @apiError UserNotFound

名稱	說明
(group)optional	所有參數將按此名稱分組。沒有組，默認錯誤4xx被設置。您可以使用@apiDefine設置標題和說明。
{type}optional	返回類型，例如 {Boolean}，{Number}，{String}，{Object}，{String []}（字符串數組），...
field	返回標識符（返回的錯誤代碼）。
descriptionoptional	說明字段。

示例:

/**
 * @api {get} /user/:id
 * @apiError UserNotFound The <code>id</code> of the User was not found.
 */

@apiErrorExample

@apiErrorExample [{type}] [title]
                 example

錯誤返回消息的示例，作為預格式化代碼輸出。

用法: @apiErrorExample {json} Error-Response: This is an example.

名稱	說明
typeoptional	響應格式。
titleoptional	示例的簡稱。
example	詳細的例子，多線程能力。

示例:

/**
 * @api {get} /user/:id
 * @apiErrorExample {json} Error-Response:
 *     HTTP/1.1 404 Not Found
 *     {
 *       "error": "UserNotFound"
 *     }
 */

@apiExample

@apiExample [{type}] title
            example

使用API方法的示例。作為預格式化代碼輸出。

在端點描述開始時將其用於完整的示例。

用法: @apiExample {js} Example usage: This is an example.

名稱	說明
typeoptional	代碼語言
title	示例的簡稱。
example	詳細的例子，多線程能力。

示例:

/**
 * @api {get} /user/:id
 * @apiExample {curl} Example usage:
 *     curl -i http://localhost/user/4711
 */

@apiGroup

@apiGroup name

應該永遠使用

定義方法文檔塊所屬的組。組將用於生成的輸出中的主導航。結構定義不需要@apiGroup。

用法: @apiGroup User

名稱	說明
name	組名稱也用作導航標題。

示例:

/**
 * @api {get} /user/:id
 * @apiGroup User
 */

@apiHeader

@apiHeader [(group)] [{type}] [field=defaultValue] [description]

描述傳遞給您的API參數授權。

類似於@apiParam的操作，只有輸出是上面的參數。

用法: @apiHeader (MyHeaderGroup) {String} authorization Authorization value.

名稱	說明
(group)optional	所有參數將按此名稱分組。沒有組，默認參數被設置。您可以使用@apiDefine設置標題和說明。
{type}optional	參數類型，例如 {Boolean}，{Number}，{String}，{Object}，{String []}（字符串數組），...
field	變量名。
[field]	帶有括號的字段名將“變量”定義為可選項。
=defaultValueoptional	參數默認值。
descriptionoptional	說明字段。

示例:

/**
 * @api {get} /user/:id
 * @apiHeader {String} access-key Users unique access-key.
 */

@apiHeaderExample

@apiHeaderExample [{type}] [title]
                   example

參數請求示例。

用法: @apiHeaderExample {json} Request-Example: { "content": "This is an example content" }

名稱	說明
typeoptional	請求格式。
titleoptional	示例的簡稱。
example	詳細的例子，多線程能力。

示例:

/**
 * @api {get} /user/:id
 * @apiHeaderExample {json} Header-Example:
 *     {
 *       "Accept-Encoding": "Accept-Encoding: gzip, deflate"
 *     }
 */

@apiIgnore

@apiIgnore [hint]

將其放在塊的頂部。

@apiIgnore的塊不會被解析。如果您在源代碼中留下過時或未完成的方法，並且不想將其發布到文檔中，這是非常有用的。

用法: @apiIgnore Not finished Method

名稱	說明
hintoptional	為什么這個塊應該被忽略的簡短信息。

示例:

/**
 * @apiIgnore Not finished Method
 * @api {get} /user/:id
 */

@apiName

@apiName name

應該永遠使用

定義方法文檔塊的名稱。名稱將用於生成輸出中的子導航。結構定義不需要@apiName。

用法: @apiName GetUser

名稱	說明
name	方法的唯一名稱。可以定義與不同@apiVersion相同的名稱。格式：方法+路徑（例如Get + User），只有一個提案，您可以按需要命名。也用作導航標題。

示例:

/**
 * @api {get} /user/:id
 * @apiName GetUser
 */

@apiParam

@apiParam [(group)] [{type}] [field=defaultValue] [description]

描述傳遞給您的API參數API方法。

用法: @apiParam (MyGroup) {Number} id Users unique ID.

Name	Description
(group)optional	所有參數將按此名稱分組。沒有組，默認參數被設置。您可以使用@apiDefine設置標題和說明。
{type}optional	參數類型，例如 {Boolean}，{Number}，{String}，{Object}，{String []}（字符串數組），...
{type{size}}optional	關於變量大小的信息。 {string {.. 5}}一個最多5個字符的字符串。 {string {2..5}}一個最小的字符串。 2個字符和最多5個字符。 {number {100-999}}一個介於100和999之間的數字。
{type=allowedValues}optional	關於變量允許值的信息。 {string =“small”}一個只能包含單詞“small”（一個常量）的字符串。 {string =“small”，“huge”}一個可以包含單詞“small”或“huge”的字符串。 {number = 1,2,3,99}一個允許值為1,2,3和99的數字。可以結合尺寸： {string {..5} =“small”，“huge”}一個字符串，最多5個字符，只包含“小”或“巨”字樣。
field	變量名。
[field]	帶有括號的字段名將“變量”定義為可選項。
=defaultValueoptional	參數默認值。
descriptionoptional	說明字段。

示例:

/**
 * @api {get} /user/:id
 * @apiParam {Number} id Users unique ID.
 */

/**
 * @api {post} /user/
 * @apiParam {String} [firstname]  Optional Firstname of the User.
 * @apiParam {String} lastname     Mandatory Lastname.
 * @apiParam {String} country="DE" Mandatory with default value "DE".
 * @apiParam {Number} [age=18]     Optional Age with default 18.
 *
 * @apiParam (Login) {String} pass Only logged in users can post this.
 *                                 In generated documentation a separate
 *                                 "Login" Block will be generated.
 */

@apiParamExample

@apiParamExample [{type}] [title]
                   example

參數請求示例。

用法: @apiParamExample {json} Request-Example: { "content": "This is an example content" }

名稱	說明
typeoptional	請求格式。
titleoptional	示例的簡稱。
example	詳細的例子，多線程能力。

示例:

/**
 * @api {get} /user/:id
 * @apiParamExample {json} Request-Example:
 *     {
 *       "id": 4711
 *     }
 */

@apiPermission

@apiPermission name

輸出權限名稱。如果使用@apiDefine定義名稱，則生成的文檔將包含附加的標題和說明。

用法: @apiPermission admin

名稱	說明
name	唯一的權限名稱。

示例:

/**
 * @api {get} /user/:id
 * @apiPermission none
 */

@apiPrivate

@apiPrivate

將API定義為私有的，以允許創建兩個API規范文檔：排除私有API和包含它們的API。

用法: @apiPrivate

排除/包含私有API的命令行用法：--private false | true

示例:

/**
 * @api {get} /user/:id
 * @apiPrivate
 */

@apiSampleRequest

@apiSampleRequest url

將此參數與apidoc.json配置參數sampleUrl配合使用。

如果設置了sampleUrl，所有方法都將具有api測試形式（將從@api的端點附加）。
沒有sampleUrl只有@apiSampleRequest的方法將有一個表單。

如果在方法塊中設置了@apiSampleRequest url，則此URL將用於請求（當以http開頭時，該url將覆蓋sampleUrl）。

如果設置了sampleUrl，並且不想使用帶有測試表單的方法，那么將@apiSampleRequest添加到文檔塊中。

用法: @apiSampleRequest http://test.github.com

名稱	說明
url	URL到您的測試api服務器。覆蓋配置參數sampleUrl並附加@api url： @apiSampleRequest http://www.example.com 前綴@api url： @apiSampleRequest / my_test_path 如果配置參數sampleUrl被設置，禁用api測試： @apiSampleRequest關閉

示例:

這將發送api請求到http://api.github.com/user/:id

Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 */

這將發送api請求到http://test.github.com/some_path/user/:id
它覆蓋sampleUrl。

Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest http://test.github.com/some_path/
 */

這將發送api請求到http://api.github.com/test/user/:id
它擴展了sampleUrl。

Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest /test
 */

這將禁用api方法的api請求。

Configuration parameter sampleUrl: "http://api.github.com"
/**
 * @api {get} /user/:id
 * @apiSampleRequest off
 */

這將發送api請求到http://api.github.com/some_path/user/:id
它僅激活此方法的請求，因為sampleUrl未設置。

Configuration parameter sampleUrl is not set
/**
 * @api {get} /user/:id
 * @apiSampleRequest http://api.github.com/some_path/
 */

@apiSuccess

@apiSuccess [(group)] [{type}] field [description]

成功返回參數。

用法: @apiSuccess {String} firstname Firstname of the User.

名稱	說明
(group)optional	所有參數將按此名稱分組。沒有組，默認的成功200被設置。您可以使用@apiDefine設置標題和說明。
{type}optional	返回類型，例如 {Boolean}，{Number}，{String}，{Object}，{String []}（字符串數組），...
field	返回標識符（返回的成功代碼）。
descriptionoptional	說明字段。

示例:

/**
 * @api {get} /user/:id
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

（組）的示例，@apiSuccessTitle中的更多組示例：

/**
 * @api {get} /user/:id
 * @apiSuccess (200) {String} firstname Firstname of the User.
 * @apiSuccess (200) {String} lastname  Lastname of the User.
 */

對象示例：

/**
 * @api {get} /user/:id
 * @apiSuccess {Boolean} active        Specify if the account is active.
 * @apiSuccess {Object}  profile       User profile information.
 * @apiSuccess {Number}  profile.age   Users age.
 * @apiSuccess {String}  profile.image Avatar-Image.
 */

數組示例：

/**
 * @api {get} /users
 * @apiSuccess {Object[]} profiles       List of user profiles.
 * @apiSuccess {Number}   profiles.age   Users age.
 * @apiSuccess {String}   profiles.image Avatar-Image.
 */

@apiSuccessExample

@apiSuccessExample [{type}] [title]
                   example

成功返回消息的示例，作為預格式化代碼輸出。

用法: @apiSuccessExample {json} Success-Response: { "content": "This is an example content" }

名稱	說明
typeoptional	響應格式。
titleoptional	示例的簡稱。
example	詳細的例子，多線程能力。

示例:

/**
 * @api {get} /user/:id
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 */

@apiUse

@apiUse name

包含一個@apiDefine定義的塊。如果與@apiVersion一起使用，將包含相同或最近的前身。

用法: @apiUse MySuccess

名稱	說明
name	定義塊的名稱。

示例:

/**
 * @apiDefine MySuccess
 * @apiSuccess {string} firstname The users firstname.
 * @apiSuccess {number} age The users age.
 */

/**
 * @api {get} /user/:id
 * @apiUse MySuccess
 */

@apiVersion

@apiVersion version

設置文檔塊的版本。版本也可以在@apiDefine中使用。

具有相同組和名稱的塊，但可以在生成的輸出中比較不同的版本，因此您或前端開發人員可以回溯自上一個版本以來API中的更改。

用法: @apiVersion 1.6.2

名稱	說明
version	支持簡單版本（major.minor.patch）。關於語義版本規范（SemVer）的更多信息。

示例:

/**
 * @api {get} /user/:id
 * @apiVersion 1.6.2
 */

更多的手表版本示例。

免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。

猜您在找 Android XML shape 標簽使用詳解（apk瘦身，減少內存好幫手） Dash——程序員的的好幫手：API文檔瀏覽器＋代碼片段管理工具 Asp.Net MVC路由調試的好幫手RouteDebugger Asp.Net MVC路由調試的好幫手RouteDebugger NPOI導入導出excel好幫手之excelhelper IIS日志-網站運維的好幫手 TED演講集 TED視頻打包下載（MP4+中英字幕） TED中英文對照字幕視頻 TED資料文檔學習英語的好幫手快速根據注釋生成接口文檔網頁工具——Apidoc的使用教程 ApiDoc使用及操作文檔畫E-R圖的好幫手——ProcessOn,愛了愛了