标签：params   about   默认   more   optional   忽略   min   versions   from   

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

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

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.

例：

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

@apiDefine

@apiDefine name [title]
                     [description]

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

@apiDefine 每块只能使用一次

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

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

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

用法： @apiDefine MyError

例：

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

例：

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

例：

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

例：

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

例：

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

例子：

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

例：

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

例：

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

@apiParam

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

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

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

可以与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" }

例：

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

覆盖配置参数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.

例：

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

例：

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

例：

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

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

标签：params   about   默认   more   optional   忽略   min   versions   from   

原文地址：https://www.cnblogs.com/wuweixiang/p/9177015.html