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

時間 2019-11-25

標籤 webapi 文檔好幫手 apidoc 使用教程简体版

原文原文鏈接

apidoc官網： http://apidocjs.com/javascript

在開發後臺接口的過程當中，咱們確定要提供一份api接口文檔給終端app。前端

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

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

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

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

有了它，咱們只須要在寫源碼的時候順手寫上一些簡單的註釋，就能夠生成出漂亮的文檔了（固然，有同窗會問文檔不是先定義的嗎？你把接口的源碼聲明好不就ok啦？或者你寫點其餘的語言也行啊。。最簡單的就是學習下javascript，只要學會怎麼建立js文件，而後怎麼聲明function，給function添加註釋便可，實在寫不了源碼，寫一個簡單的js文件，而後用apidoc生成一下就出文檔了。）。shell

它能夠對API的各類版本等級進行對比。因此不管是前端開發人員仍是你均可以追溯API版本的變化。
npm

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

使用步驟：

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
 */

更多的手錶版本示例。

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。