RESTful web API Documentation Generator. http://apidocjs.com

入门

前言

本文档中的所有示例都使用Javadoc-Style（可用于C＃，Go，Dart，Java，JavaScript，PHP，TypeScript和所有其他支持Javadoc的语言）：

/*** This is a comment.*/

安装

npm install apidoc -g

配置（apidoc.json）

apidoc.json项目中的可选项root dir包含有关项目的常用信息，如标题，简短说明，版本和配置选项，如页眉/页脚设置或模板特定选项。

Name	Description
name	Name of your project.
If no apidoc.json with the field exists, then apiDoc try to determine the the value from package.json.
version	Version of your project.
If no apidoc.json with the field exists, then apiDoc try to determine the the value from package.json.
description	Introduction of your project.
If no apidoc.json with the field exists, then apiDoc try to determine the the value from package.json.
title	Browser title text.
url	Prefix for api path (endpoints), e.g. https://api.github.com/v1
sampleUrl	If set, a form to test an api method (send a request) will be visible. See @apiSampleRequest for more details.
header
title	Navigation text for the included header.md file.
(watch Header / Footer)
filename	Filename (markdown-file) for the included header.md file.
footer
title	Navigation text for the included footer.md file.
filename	Filename (markdown-file) for the included footer.md file.
order	A list of api-names / group-names for ordering the output. Not defined names are automatically displayed last.

"order": ["Error","Define","PostTitleAndError","PostError"
]

|

在您的项目中，apidoc.json您可以添加页眉和页脚。

{ "header": { "title": "My own header title", "filename": "header.md" }, "footer": { "title": "My own footer title", "filename": "footer.md" } }

以下设置是特定于apiDoc的默认模板的。

Name	Type	Description
template
forceLanguage	String	Disable browser language auto-detection and set a specific locale.
Example: de, en.
View available locales here.
withCompare	Boolean	Enable comparison with older api versions. Default: true
withGenerator	Boolean	Output the generator information at the footer. Default: true
jQueryAjaxSetup	Object	Set default values for Ajax requests.

apidoc.json实例

{"name": "项目名称","version": "1.0.0","description": "介绍你的项目","title": "浏览器标题文本","url" : "Api路径前缀，例如：http://localhost:8080","sampleUrl": "所有方法都将具有API测试表单http://localhost:10086","header": {"title": "页头标题Overview","filename": "header.md"},"footer": {"title": "页脚标题","filename": "footer.md"},"template": {"withCompare": true,"withGenerator": true}
}

继承

使用继承，您可以定义文档的可重用片段。

定义一个继承块，请使用apiDefine。
引用一个块，使用apiUse。

继承仅适用于1个父级

``/**

• **@apiDefine** UserNotFoundError *
• @apiError UserNotFound The id of the User was not found. *
• @apiErrorExample Error-Response:
• HTTP/1.1 404 Not Found
• {
• "error": "UserNotFound"
• } */

/**

• @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"
• } *
• **@apiUse** UserNotFoundError */

/**

• @api {put} /user/ Modify User information
• @apiName PutUser
• @apiGroup User *
• @apiParam {Number} id Users unique ID.
• @apiParam {String} [firstname] Firstname of the User.
• @apiParam {String} [lastname] Lastname of the User. *
• @apiSuccessExample Success-Response:
• HTTP/1.1 200 OK *
• **@apiUse** UserNotFoundError */``

版本

在示例中，在选择框（主版本）上单击右上角并选择Compare changes to。

• 主导航标记全部用绿色条改变了方法。
• 每种方法都显示与其前身相比的实际差异。
• 绿色标记添加的内容（在这种情况下，标题文本已更改，字段registered已添加）。
• 红色标记已删除的内容。

apidoc.json

{ "name": "example-versioning", "version": "0.2.0", "description": "apiDoc versioning example" }

为了避免API文档随时间变化而导致代码膨胀，建议使用名为的单独历史文件_apidoc.js。在更改文档块之前，将旧文档复制到此文件，apiDoc将自动包含历史信息。

_apidoc.js（单独历史文件）

``/**

• @api {get} /user/:id Get User information
• **@apiVersion** 0.1.0
• @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"
• } */``

example.js（当前的项目文件）

``/**

• @api {get} /user/:id Get User information and Date of Registration.
• **@apiVersion 0.2.0**
• @apiName GetUser
• @apiGroup User *
• @apiParam {Number} id Users unique ID. *
• @apiSuccess {String} firstname Firstname of the User.
• @apiSuccess {String} lastname Lastname of the User.
• @apiSuccess {Date} registered Date of Registration. *
• @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"
• } */``

重要的是@apiVersion在每个文档块上设置版本。

该版本可以在每个块上使用，也可以在继承块上使用。您不必在继承块上更改版本，解析器会自动检查最近的前辈。

apiDoc-PARAMS

@api

@api {method} path [title]

需要！

如果没有该指标，apiDoc解析器会忽略文档块。

唯一的例外是由@apiDefine它们定义的文档块 ，它们不是必需的[@api](https://my.oschina.net/u/2396174)。

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

名称	描述
method	请求方法名称：DELETE，GET，POST，PUT，…
更多信息维基百科的HTTP-Request_methods
path	请求路径。
title 可选	简短的标题。（用于导航和文章标题）

例：

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

@apiDefine

@apiDefine name [title][description]

定义一个文档块以嵌入到@api块或类似的api函数中@apiPermission。

@apiDefine 每块只能使用一次

通过使用@apiUse定义的块将被导入，或者使用标题和描述的名称将被使用。

用于定义可重用的文档块。该块可以包含在普通的api文档块中。使用@apiDefine允许您更好地组织复杂的文档并避免复制经常性块。

定义的块可以包含所有的参数（像@apiParam），除了其他定义的块。

用法： @apiDefine MyError

名称	描述
name	块/值的唯一名称。可以定义
不同的同名@apiVersion。
title 可选	简短的标题。仅用于指定的功能，如@apiPermission或@apiParam (name)。
description 可选	详细说明从下一行开始，可以使用多行。仅用于像@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.

名称	描述
文本	多行描述文本。

例：

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

@apiError

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

错误返回参数。

用法： @apiError UserNotFound

名称	描述
（group） 可选	所有参数将按这个名称分组。
没有组，默认Error 4xx设置。
您可以使用@apiDefine设置标题和描述。
{type} 可选	返回类型，例如{Boolean}， {Number}， {String}，{Object}，{String[]}（字符串数组），…
领域	返回标识符（返回的错误代码）。
描述 可选	该领域的描述。

例：

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

名称	描述
{type} 可选	响应格式。
title 可选	示例的简称。
example	详细的例子，multilines能力。

例：

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

@apiExample

@apiExample [{type}] titleexample

使用API​​方法的示例。以预格式化的代码输出。

在端点描述的开始处使用它作为完整的示例。

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

名称	描述
type 可选	代码语言。
title	示例的简称。
example	详细的例子，multilines能力。

例：

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

@apiGroup

@apiGroup name

应该始终使用。

定义方法文档块属于哪个组。组将用于生成的输出中的主导航。结构定义不需要@apiGroup。

用法： @apiGroup User

名称	描述
名称	组的名称。也用作导航标题。

例：

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

@apiHeader

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

描述传递给你的参数API-Header，例如Authorization。

与@apiParam类似的操作，只有输出高于参数。

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

名称	描述
（group） 可选	所有参数将按这个名称分组。
没有组，默认Parameter设置。
您可以使用@apiDefine设置标题和描述。
{type} 可选	参数类型，例如{Boolean}， {Number}， {String}，{Object}，{String[]}（字符串数组），…
[field]	带括号的字段名称将变量定义为可选。
= defaultValue 可选	参数的默认值。
description 可选	该领域的描述。

例子：

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

名称	描述
类型可选	请求格式。
标题可选	示例的简称。
例	详细的例子，multilines能力。

例：

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

@apiIgnore

@apiIgnore [hint]

将它放在块的顶部。

一个块@apiIgnore将不被解析。如果您在源代码中保留过时或未完成的方法并且您不希望将其发布到文档中，这是有用的。

用法： @apiIgnore Not finished Method

名称	描述
提示可选	短信息为什么应该忽略这个块。

例：

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

@apiName

@apiName name

应该始终使用。

定义方法文档块的名称。名称将用于生成的输出中的子导航。结构定义不需要@apiName。

用法： @apiName GetUser

名称	描述
名称	方法的唯一名称。@apiVersion可以定义不同的同名。
格式：方法 + 路径（例如Get + User），只有一个提案，你可以任意命名。
也用作导航标题。

例：

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

@apiParam

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

描述传递给你的参数API-Method。

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

名称	描述
（group）可选	所有参数将按这个名称分组。
没有组，默认Parameter设置。
您可以使用@apiDefine设置标题和描述。
{type} 可选	参数类型，例如{Boolean}，{Number}，{String}，{Object}，{String[]}（字符串数组），…
{type {size}} 可选	有关变量大小的信息。
{string{..5}}最多5个字符的字符串。
{string{2..5}}最小的字符串。2个字符和最多5个字符。
{number{100-999}}介于100和999之间的数字。
{type = allowedValues} 可选	有关变量允许值的信息。
{string="small"}一个只能包含单词“small”（常量）的字符串。
{string="small","huge"}一个可以包含单词“小”或“巨大”的字符串。
{number=1,2,3,99}一个允许值为1，2，3和99的数字。

可以与size组合：
{string {..5}="small","huge"}一个字符串，它具有最多5个字符，并且只包含“small”或“huge”字样。 | | filed | 变量名。 | | [filed] | 带括号的字段名称将变量定义为可选。 | | = defaultValue 可选 | 参数的默认值。 | | description 可选 | 该领域的描述。 |

例子：

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

名称	描述
type 可选	请求格式。
title 可选	示例的简称。
example	详细的例子，multilines能力。

例：

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

@apiPermission

@apiPermission name

输出权限名称。如果名称是用@apiDefine生成的文档定义的，则包括附加的标题和说明。

用法： @apiPermission admin

名称	描述
名称	权限的唯一名称。

例：

/*** @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开头时，它将覆盖sampleUrl）。

如果sampleUrl已设置并且您不想使用测试表单的方法，请将其添加@apiSampleRequest off到文档块中。

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

名称	描述
url	网址到您的测试api服务器。

覆盖配置参数sampleUrl并追加@api url：
@apiSampleRequest http://www.example.com

前缀@api url：
@apiSampleRequest /my_test_path

如果配置参数sampleUrl被设置，则禁用API测试：
@apiSampleRequest off |

例子：

这会将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） 可选	所有参数将按这个名称分组。
没有组，默认Success 200设置。
您可以使用@apiDefine设置标题和描述。
{type} 可选	返回类型，例如{Boolean}， {Number}， {String}，{Object}，{String[]}（字符串数组），…
field	返回标识符（返回的成功代码）。
description 可选	该领域的描述。

例：

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

示例(group)，@ 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" }

名称	描述
type 可选	响应格式。
title 可选	示例的简称。
example	详细的例子，multilines能力。

例：

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

@apiUse

@apiUse name

包含一个带有@apiDefine定义的块。如果与@apiVersion相同或最近的前辈一起使用将被包括在内。

用法： @apiUse MySuccess

名称	描述
名称	定义块的名称。

例：

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

更多手表版本示例。

完整的例子

这是一个复杂的例子inherit，versioning文件和历史文件_apidoc.js，解释在代码和生成文档中。

查看示例输出

文件：

• _apidoc.js

// ------------------------------------------------------------------------------------------
// General apiDoc documentation blocks and old history blocks.
// ------------------------------------------------------------------------------------------// ------------------------------------------------------------------------------------------
// Current Success.
// ------------------------------------------------------------------------------------------// ------------------------------------------------------------------------------------------
// Current Errors.
// ------------------------------------------------------------------------------------------
/*** @apiDefine CreateUserError* @apiVersion 0.2.0** @apiError NoAccessRight Only authenticated Admins can access the data.* @apiError UserNameTooShort Minimum of 5 characters required.** @apiErrorExample  Response (example):*     HTTP/1.1 400 Bad Request*     {*       "error": "UserNameTooShort"*     }*/// ------------------------------------------------------------------------------------------
// Current Permissions.
// ------------------------------------------------------------------------------------------
/*** @apiDefinePermission admin Admin access rights needed.* Optionally you can write here further Informations about the permission.** An "apiDefinePermission"-block can have an "apiVersion", so you can attach the block to a specific version.** @apiVersion 0.3.0*/// ------------------------------------------------------------------------------------------
// History.
// ------------------------------------------------------------------------------------------
/*** @apiDefinePermission admin This title is visible in version 0.1.0 and 0.2.0* @apiVersion 0.1.0*//*** @api {get} /user/:id Read data of a User* @apiVersion 0.2.0* @apiName GetUser* @apiGroup User* @apiPermission admin** @apiDescription Here you can describe the function.* Multilines are possible.** @apiParam {String} id The Users-ID.** @apiSuccess {String} id         The Users-ID.* @apiSuccess {Date}   name       Fullname of the User.** @apiError UserNotFound   The <code>id</code> of the User was not found.*//*** @api {get} /user/:id Read data of a User* @apiVersion 0.1.0* @apiName GetUser* @apiGroup User* @apiPermission admin** @apiDescription Here you can describe the function.* Multilines are possible.** @apiParam {String} id The Users-ID.** @apiSuccess {String} id         The Users-ID.* @apiSuccess {Date}   name       Fullname of the User.** @apiError UserNotFound   The error description text in version 0.1.0.*//*** @api {post} /user Create a User* @apiVersion 0.2.0* @apiName PostUser* @apiGroup User* @apiPermission none** @apiDescription In this case "apiUse" is defined and used.* Define blocks with params that will be used in several functions, so you dont have to rewrite them.** @apiParam {String} name Name of the User.** @apiSuccess {String} id         The Users-ID.** @apiUse CreateUserError*/

• example.js

/*** @api {get} /user/:id Read data of a User* @apiVersion 0.3.0* @apiName GetUser* @apiGroup User* @apiPermission admin** @apiDescription Compare Verison 0.3.0 with 0.2.0 and you will see the green markers with new items in version 0.3.0 and red markers with removed items since 0.2.0.** @apiParam {String} id The Users-ID.** @apiExample Example usage:* curl -i http://localhost/user/4711** @apiSuccess {String}   id            The Users-ID.* @apiSuccess {Date}     registered    Registration Date.* @apiSuccess {Date}     name          Fullname of the User.* @apiSuccess {String[]} nicknames     List of Users nicknames (Array of Strings).* @apiSuccess {Object}   profile       Profile data (example for an Object)* @apiSuccess {Number}   profile.age   Users age.* @apiSuccess {String}   profile.image Avatar-Image.* @apiSuccess {Object[]} options       List of Users options (Array of Objects).* @apiSuccess {String}   options.name  Option Name.* @apiSuccess {String}   options.value Option Value.** @apiError NoAccessRight Only authenticated Admins can access the data.* @apiError UserNotFound   The <code>id</code> of the User was not found.** @apiErrorExample Response (example):*     HTTP/1.1 401 Not Authenticated*     {*       "error": "NoAccessRight"*     }*/
function getUser() { return; }/*** @api {post} /user Create a new User* @apiVersion 0.3.0* @apiName PostUser* @apiGroup User* @apiPermission none** @apiDescription In this case "apiUse" is defined and used.* Define blocks with params that will be used in several functions, so you dont have to rewrite them.** @apiParam {String} name Name of the User.** @apiSuccess {String} id         The new Users-ID.** @apiUse CreateUserError*/
function postUser() { return; }/*** @api {put} /user/:id Change a new User* @apiVersion 0.3.0* @apiName PutUser* @apiGroup User* @apiPermission none** @apiDescription This function has same errors like POST /user, but errors not defined again, they were included with "apiUse"** @apiParam {String} name Name of the User.** @apiUse CreateUserError*/
function putUser() { return; }

• apidoc.json

{
"name": "apidoc-example",
"version": "0.3.0",
"description": "apiDoc example project",
"title": "Custom apiDoc browser title",
"url": "https://api.github.com/v1",
"header": {
"title": "My own header title",
"filename": "header.md"
},
"footer": {
"title": "My own footer title",
"filename": "footer.md"
},
"order": [
"GetUser",
"PostUser"
],
"template": {
"withCompare": true,
"withGenerator": true
}
}