歡迎關(guān)注微信公眾號：全棧工廠

本文主要參考

• ApiDoc官方文檔

一、apidoc簡介

apidoc是一款可以有源代碼中的注釋直接自動生成api接口文檔的工具，它幾乎支持目前主流的所有風(fēng)格的注釋。例如：
Javadoc風(fēng)格注釋(可以在C#, Go, Dart, Java, JavaScript, PHP, TypeScript等語言中使用)

/**
 * This is a comment.
 */

CoffeeScript

###
This is a comment.
###

Elixir

@apidoc """
This is a comment.
"""

Erlang (注釋中的‘%’是可選的)

%{
% This is a comment.
%}

Perl (Doxygen)

#**
# This is a comment.
#*

Python

"""
This is a comment.
"""

Ruby

=begin
This is a comment.
=end

Lua

--[[
This is a comment.
--]]

二、apidoc使用

可以通過以下命令安裝apidoc:

npm install apidoc -g

運(yùn)行：

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

2.1 apidoc 命令參數(shù)列表：

2.2 配置(apidoc.json)

每次導(dǎo)出接口文檔都必須要讓apidoc讀取到apidoc.json文件(如果未添加配置文件，導(dǎo)出報錯)，你可以在你項(xiàng)目的根目錄下添加apidoc.json文件，這個文件主要包含一些項(xiàng)目的描述信息，比如標(biāo)題、簡短的描述、版本等，你也可以加入一些可選的配置項(xiàng)，比如頁眉、頁腳、模板等。
apidoc.json

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "title": "Custom apiDoc browser title",
  "url" : "https://api.github.com/v1"
}

如果你的項(xiàng)目中使用了package.json文件(例如:node.js工程)，那么你可以將apidoc.json文件中的所有配置信息放到package.json文件中的apidoc參數(shù)中：
package.json

{
  "name": "example",
  "version": "0.1.0",
  "description": "apiDoc basic example",
  "apidoc": {
    "title": "Custom apiDoc browser title",
    "url" : "https://api.github.com/v1"
  }
}

apidoc.json配置項(xiàng)

三、 apidoc注釋參數(shù)

3.1 @api

【必填字段】否則，apidoc會忽略該條注釋

@api {method} path [title]

參數(shù)列表:

例：

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

3.2 @apiDefine

@apiDefine name [title]
                     [description]

定義注釋模塊(類似于代碼中定義一個常量)，對于一些通用可復(fù)用的注釋模塊(例如:接口錯誤響應(yīng)模塊),只需要在源代碼中定義一次，便可以在其他注釋模塊中隨便引用，最后在文檔導(dǎo)出時會自動替換所引用的注釋模塊，定義之后您可以通過@apiUse來引入所定義的注釋模塊。(注:可以同時使用@apiVersion來定義注釋模塊的版本)
參數(shù)列表：

例:

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

3.3 @apiDeprecated

@apiDeprecated [text]

標(biāo)注一個接口已經(jīng)被棄用
參數(shù)列表:

例：

**
 * @apiDeprecated
 */

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

3.4 @apiDescription

@apiDescription text

api接口的詳細(xì)描述
參數(shù)列表:

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

3.5 @apiError

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

錯誤返回參數(shù)
參數(shù)列表:

例:

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

3.6 @apiErrorExample

@apiErrorExample [{type}] [title]
                 example

接口錯誤返回示例(格式化輸出)
參數(shù)列表:

例:

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

3.7 @apiExample

@apiExample [{type}] title
            example

接口方式請求示例
參數(shù)列表:

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

3.8 @apiGroup

@apiGroup name

定義接口所屬的接口組，雖然接口定義里不需要這個參數(shù)，但是您應(yīng)該在每個接口注釋里都添加這個參數(shù)，因?yàn)閷?dǎo)出的接口文檔會以接口組的形式導(dǎo)航展示。
參數(shù)列表:

例：

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

3.9 @apiHeader

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

描述接口請求頭部需要的參數(shù)(功能類似@apiParam)
參數(shù)列表:

例:

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

3.10 @apiHeaderExample

@apiHeaderExample [{type}] [title]
                   example

請求頭部參數(shù)示例
參數(shù)列表:

例：

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

3.11 @apiIgnore

@apiIgnore [hint]

如果你需要使用該參數(shù)，請把它放到注釋塊的最前面。如果設(shè)置了該參數(shù)，那么該注釋模塊將不會被解析(當(dāng)有些接口還未完成或未投入使用時，可以使用該字段)
參數(shù)列表:

例：

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

3.12 @apiName

@apiName name

接口名稱，每一個接口注釋里都應(yīng)該添加該字段，在導(dǎo)出的接口文檔里會已該字段值作為導(dǎo)航子標(biāo)題，如果兩個接口的@apiVersion和@apiName一樣，那么有一個接口的注釋將會被覆蓋(接口文檔里不會展示)
參數(shù)列表:

例：

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

3.13 @apiParam

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

接口請求體參數(shù)
參數(shù)列表:

例:

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

3.14 @apiParamExample

@apiParamExample [{type}] [title]
                   example

請求體參數(shù)示例
參數(shù)列表:

例：

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

3.15 @apiPermission

允許訪問該接口的角色名稱

@apiPermission name

參數(shù)列表:

例：

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

3.16 @apiPrivate

@apiPrivate

定義私有接口，對于定義為私有的接口，可以在生成接口文檔的時候，通過在命令行中設(shè)置參數(shù) --private false|true來決定導(dǎo)出的文檔中是否包含私有接口
例：

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

3.17 @apiSampleRequest

@apiSampleRequest url

設(shè)置了該參數(shù)后，導(dǎo)出的html接口文檔中會包含模擬接口請求的form表單；如果在配置文件apidoc.json中設(shè)置了參數(shù)sampleUrl,那么導(dǎo)出的文檔中每一個接口都會包含模擬接口請求的form表單，如果既設(shè)置了sampleUrl參數(shù)，同時也不希望當(dāng)前這個接口不包含模擬接口請求的form表單，可以使用@apiSampleRequest off來關(guān)閉。
參數(shù)列表:

例：
發(fā)送測試請求到:http://api.github.com/user/:id

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

發(fā)送測試請求到:http://test.github.com/some_path/user/:id(覆蓋apidoc.json中的sampleUrl參數(shù))

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

關(guān)閉接口測試功能

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

發(fā)送測試請求到http://api.github.com/some_path/user/:id(由于沒有設(shè)置apidoc.json中的sampleUrl參數(shù)，所以只有當(dāng)前接口有模擬測試功能)

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

3.18 @apiSuccess

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

接口成功返回參數(shù)
參數(shù)列表:

例:

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

包含(group):

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

返回參數(shù)中有對象:

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

返回參數(shù)中有數(shù)組：

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

3.19 @apiSuccessExample

@apiSuccessExample [{type}] [title]
                   example

返回成功示例
參數(shù)列表:

例：

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

3.20@apiUse

@apiUse name

引入注釋模塊，如果當(dāng)前模塊定義了@apiVersion,那么版本相同或版本最近的注釋模塊會被引入
參數(shù)列表:

例:

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

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

3.21 @apiVersion

@apiVersion version

定義接口/注釋模塊版本
參數(shù)列表:

例:

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

注：文中如有任何錯誤，請各位批評指正！