目錄

一、apidoc簡(jiǎn)介

二、apidoc安裝使用

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

2.2 配置(apidoc.json)

三、 apidoc注釋參數(shù)

3.1 @api

3.2 @apiDefine

3.3 @apiDeprecated

3.4 @apiDescription

3.5 @apiError

3.6 @apiErrorExample

3.7 @apiExample

3.8 @apiGroup

3.9 @apiHeader

3.10 @apiHeaderExample

3.11 @apiIgnore

3.12 @apiName

3.13 @apiParam

3.14 @apiParamExample

3.15 @apiPermission

3.16 @apiPrivate

3.17 @apiSampleRequest

3.18 @apiSuccess

3.19 @apiSuccessExample

3.20@apiUse

3.21 @apiVersion

---

一、apidoc簡(jiǎn)介

Git地址：https://github.com/apidoc/apidoc?
項(xiàng)目地址：http://apidocjs.com/?
樣例項(xiàng)目：http://apidocjs.com/example_basic/?

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

/*** 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安裝使用

下載安裝node.js?官網(wǎng)地址：https://nodejs.org/en/? ?注意：版本不能太低? apidoc對(duì)nodejs版本有要求

通過以下命令安裝apidoc:

npm install apidoc -g

運(yùn)行生產(chǎn)文檔：

apidoc -i vtools/ -o static/docs

其中apidoc.json文件存在于?vtools 目錄下

運(yùn)行成功將返回：

{"message":"Done.","level":"info"}

?

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

參數(shù)	描述
-h, --help	查看幫助文檔
-f --file-filters	指定讀取文件的文件名過濾正則表達(dá)式(可指定多個(gè)) 例如: apidoc -f ".*\\.js$" -f ".*\\.ts$" 意為只讀取后綴名為js和ts的文件 默認(rèn)值:.clj .cls .coffee .cpp .cs .dart .erl .exs? .go .groovy .ino? .java .js .jsx .kt .litcoffee lua .p .php? .pl .pm .py .rb .scala .ts .vue
-e --exclude-filters	指定不讀取的文件名過濾正則表達(dá)式(可指定多個(gè)) 例如:apidoc -e ".*\\.js$" 意為不讀取后綴名為js的文件 默認(rèn):''
-i, --input	指定讀取源文件的目錄 例如：apidoc -i myapp/ 意為讀取myapp/目錄下面的源文件 默認(rèn)值:./
-o, --output	指定輸出文檔的目錄 例如：apidoc -o doc/ 意為輸出文檔到doc目錄下 默認(rèn)值:./doc/
-t, --template	指定輸出的模板文件 例如:apidoc -t mytemplate/ 默認(rèn):path.join(__dirname, '../template/')(使用默認(rèn)模板)
-c, --config	指定包含配置文件(apidoc.json)的目錄 例如:apidoc -c config/ 默認(rèn):./
-p, --private	輸出的文檔中是否包含私有api 例如:apidoc -p true 默認(rèn):false
-v, --verbose	是否輸出詳細(xì)的debug信息 例如:apidoc -v true 默認(rèn):false

2.2 配置(apidoc.json)

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

參數(shù)	描述
name	工程名稱 如果apidoc.json文件中沒有配置該參數(shù)，apidoc會(huì)嘗試從pakcage.json文件中讀取
version	版本 如果apidoc.json文件中沒有配置該參數(shù)，apidoc會(huì)嘗試從pakcage.json文件中讀取
description	工程描述 如果apidoc.json文件中沒有配置該參數(shù)，apidoc會(huì)嘗試從pakcage.json文件中讀取
title	瀏覽器標(biāo)題
url	api路徑前綴 例如:https://api.github.com/v1
sampleUrl	如果設(shè)置了該參數(shù)，那么在文檔中便可以看到用于測(cè)試接口的一個(gè)表單(詳情可以查看參數(shù)@apiSampleReques)
header.title	頁(yè)眉導(dǎo)航標(biāo)題
header.filename	頁(yè)眉文件名(markdown)
footer.title	頁(yè)腳導(dǎo)航標(biāo)題
footer.filename	頁(yè)腳文件名(markdown)
order	接口名稱或接口組名稱的排序列表 如果未定義，那么所有名稱會(huì)自動(dòng)排序 "order":[ ?????"Error", ?????"Define", ?????"PostTitleAndError", ?????"PostError" ]

三、 apidoc注釋參數(shù)

3.1 @api

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

@api {method} path [title]

參數(shù)列表:

參數(shù)	必填	描述
method	yes	請(qǐng)求類型:DELETE, GET, POST, PUT, ...更多
path	yes	請(qǐng)求路徑
title	no	接口標(biāo)題

例：

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

3.2 @apiDefine

@apiDefine name [title][description]

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

參數(shù)	必填	描述
name	yes	注釋模塊名稱(唯一)，不同@apiVersion可以定義相同名稱的注釋模塊
title	no	注釋模塊標(biāo)題
description	no	注釋模塊詳細(xì)描述(詳細(xì)描述另起一行，可包含多行)

例:

/*** @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)注一個(gè)接口已經(jīng)被棄用
參數(shù)列表:

參數(shù)	必填	描述
text	yes	多行文字描述

例：

*** @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ù)列表:

參數(shù)	必填	描述
text	yes	多行文字描述

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

3.5 @apiError

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

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

參數(shù)	必填	描述
(group)	no	所有的參數(shù)都會(huì)通過這個(gè)參數(shù)進(jìn)行分組，如果未設(shè)置，默認(rèn)值為Error 4xx
{type}	no	返回類型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
field	yes	返回id
description	no	參數(shù)描述

例:

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

3.6 @apiErrorExample

@apiErrorExample [{type}] [title]example

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

參數(shù)	必填	描述
type	no	響應(yīng)類型
title	no	示例標(biāo)題
example	yes	示例詳情(兼容多行)

例:

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

3.7 @apiExample

@apiExample [{type}] titleexample

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

參數(shù)	必填	描述
type	no	請(qǐng)求內(nèi)容格式
title	yes	示例標(biāo)題
example	yes	示例詳情(兼容多行)

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

3.8 @apiGroup

@apiGroup name

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

參數(shù)	必填	描述
name	yes	接口組名稱(用于導(dǎo)航,不支持中文)

例：

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

3.9 @apiHeader

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

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

參數(shù)	必填	描述
(group)	no	所有的參數(shù)都會(huì)以該參數(shù)值進(jìn)行分組(默認(rèn)Parameter)
{type}	no	返回類型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
field	yes	參數(shù)名稱(定義該頭部參數(shù)為必填)
[field]	yes	參數(shù)名稱(定義該頭部參數(shù)為可選)
=defaultValue	no	參數(shù)默認(rèn)值
description	no	參數(shù)描述

例:

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

3.10 @apiHeaderExample

@apiHeaderExample [{type}] [title]example

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

參數(shù)	必填	描述
type	no	請(qǐng)求內(nèi)容格式
title	no	請(qǐng)求示例標(biāo)題
example	yes	請(qǐng)求示例詳情(兼容多行)

例：

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

3.11 @apiIgnore

@apiIgnore [hint]

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

參數(shù)	必填	描述
hint	no	描接口忽略原因描述

例：

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

3.12 @apiName

@apiName name

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

參數(shù)	必填	描述
name	yes	接口名稱(相同接口版本下所有接口名稱應(yīng)該是唯一的)

例：

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

3.13 @apiParam

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

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

參數(shù)	必填	描述
(group)	no	所有的參數(shù)都會(huì)以該參數(shù)值進(jìn)行分組(默認(rèn)Parameter)
{type}	no	返回類型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
{type{size}}	no	返回類型,同時(shí)定義參數(shù)的范圍 {string{..5}}意為字符串長(zhǎng)度不超過5 {string{2..5}}意為字符串長(zhǎng)度介于25之間<br/>`{number{100-999}}`意為數(shù)值介于100999之間
{type=allowedValues}	no	參數(shù)可選值 {string="small"}意為字符串僅允許值為"small" {string="small","huge"}意為字符串允許值為"small"、"huge" {number=1,2,3,99}意為數(shù)值允許值為1、2、3、99 {string {..5}="small","huge"意為字符串最大長(zhǎng)度為5并且值允許為:"small"、"huge"
field	yes	參數(shù)名稱(定義該請(qǐng)求體參數(shù)為必填)
[field]	yes	參數(shù)名稱(定義該請(qǐng)求體參數(shù)為可選)
=defaultValue	no	參數(shù)默認(rèn)值
description	no	參數(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

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

參數(shù)	必填	描述
type	no	請(qǐng)求內(nèi)容格式
title	no	請(qǐng)求示例標(biāo)題
example	yes	請(qǐng)求示例詳情(兼容多行)

例：

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

3.15 @apiPermission

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

@apiPermission name

參數(shù)列表:

參數(shù)	必填	描述
name	yes	允許訪問的角色名稱(唯一)

例：

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

3.16 @apiPrivate

@apiPrivate

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

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

3.17 @apiSampleRequest

@apiSampleRequest url

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

參數(shù)	必填	描述
url	yes	模擬接口請(qǐng)求的url @apiSampleRequest http://www.example.com意為覆蓋apidoc.json中的sampleUrl參數(shù) @apiSampleRequest off意為關(guān)閉接口測(cè)試功能

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

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

發(fā)送測(cè)試請(qǐng)求到: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)閉接口測(cè)試功能

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

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

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ù)列表:

參數(shù)	必填	描述
(group)	no	所有的參數(shù)都會(huì)以該參數(shù)值進(jìn)行分組,默認(rèn)值:Success 200
{type}	no	返回類型(例如:{Boolean}, {Number}, {String}, {Object}, {String[]})
field	yes	返回值(返回成功碼)
=defaultValue	no	參數(shù)默認(rèn)值
description	no	參數(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ù)中有對(duì)象:

/*** @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ù)列表:

參數(shù)	必填	描述
type	no	返回內(nèi)容格式
title	no	返回示例標(biāo)題
example	yes	返回示例詳情(兼容多行)

例：

/*** @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,那么版本相同或版本最近的注釋模塊會(huì)被引入
參數(shù)列表:

參數(shù)	必填	描述
name	yes	引入注釋模塊的名稱

例:

/*** @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ù)列表:

參數(shù)	必填	描述
version	yes	版本號(hào)(支持APR版本規(guī)則:major.minor.patch)

例:

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

注：文中如有任何錯(cuò)誤，請(qǐng)各位批評(píng)指正！

?

總結(jié)

以上是生活随笔為你收集整理的ApiDoc官方文档的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。