apiDoc构建源代码注释的接口文档

Posted wuweixiang

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了apiDoc构建源代码注释的接口文档相关的知识，希望对你有一定的参考价值。

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包含有关项目的常用信息，如标题，简短说明，版本和配置选项，如页眉/页脚设置或模板特定选项。

NameDescription
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的默认模板的。

NameTypeDescription
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}] title
            example

使用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，解释在代码和生成文档中。

查看示例输出

文件：

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









以上是关于apiDoc构建源代码注释的接口文档的主要内容，如果未能解决你的问题，请参考以下文章

APIDOC官方文档(翻译版) 使用文档

Web API文档生成工具apidoc

用apiDoc简化接口开发

浅谈apidoc的使用

快速根据注释生成接口文档网页工具——Apidoc的使用教程

企业级 SpringBoot 教程 springboot集成apidoc