文档章节

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

吴伟祥
 吴伟祥
发布于 06/13 11:02
字数 4309
阅读 556
收藏 4

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

入门

前言

本文档中的所有示例都使用Javadoc-Style(可用于C#,Go,Dart,Java,JavaScript,PHP,TypeScript和所有其他支持Javadoc的语言):

/**
 * This is a comment.
 */

安装

一、安装nodeJs

根据每个人的操作系统是选择对应的node安装包。譬如,笔者是64位Windows操作系统,如下图所示:

 

 1、点击进行逐步安装即可。注:高版本的JS自带了NPM,故不用另外去安装NPM。

 2、Win+R输入cmd,进行查看安装状态是否成功。

二、安装apidoc

1、输入命令: npm install apidoc –g

1527069644194-133.png

 2、Win+R输入cmd,进行查看安装状态是否成功。

1527069312127-241.png

到此安装工作已经完成。

构建

1527070133039-851.png

配置(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: deen.
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

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

名称 描述
method 请求方法名称:DELETEGETPOSTPUT,... 
更多信息维基百科的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
 */

更多手表版本示例

完整的例子

这是一个复杂的例子inheritversioning文件和历史文件_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
}
}

© 著作权归作者所有

吴伟祥
粉丝 8
博文 322
码字总数 212508
作品 0
泉州
后端工程师
使用apidoc文档神器,快速生成api文档

写完api接口,就需要编写api文档了,如果一个个手写的话就很麻烦,就得使用apidoc只需要通过写注释,就可以快速生成文档了。 安装 第一步先安装全局模块apidoc。 修改接口的注释 找到novel-a...

jilei786
06/14
0
0
KingWTD/mockcat

Mockcat 开发工具集 项目简介 Mockcat是一款前端与后台分离开发的简易的接口Mock数据工具。提供了mock数据的模块化管理,接口数据的定义(支持带注释的JSON数据,自带JSON数据编辑器),以及...

KingWTD
08/22
0
0
javadoc工具生成自己的API文档

javadoc默认只处理public和protected修饰的内容,如果要提取private,只需在用javadoc时加-private选项。 另外javadoc只处理文档注释即为/**..................*/和只有对处于多个包下面大源...

zhengDavid
2012/06/12
0
0
RESTFul接口测试工具:Wisdom RESTClient

Wisdom RESTClient 是由个人所开发的一款自动化测试REST API的工具。 它可以自动化测试REST API并生成精美的测试报告,同时基于测试过的历史数据,可以生成精美的REST API文档。 使用注意事项...

niithub
05/01
0
0
基于 Groovy 的 Web 框架 - Grails

Grails 是一套用于快速 Web 应用开发的开源框架,它基于 Groovy 编程语言,并构建于 Spring、Hibernate 和其它标准 Java 框架之上,从而为大家带来一套能实现超高生产力的一站式框架。 Ruby...

匿名
2008/09/12
0
2

没有更多内容

加载失败,请刷新页面

加载更多

70.shell的函数 数组 告警系统需求分析

20.16/20.17 shell中的函数 20.18 shell中的数组 20.19 告警系统需求分析 20.16/20.17 shell中的函数: ~1. 函数就是把一段代码整理到了一个小单元中,并给这个小单元起一个名字,当用到这段...

王鑫linux
今天
0
0
分布式框架spring-session实现session一致性使用问题

前言:项目中使用到spring-session来缓存用户信息,保证服务之间session一致性,但是获取session信息为什么不能再服务层获取? 一、spring-session实现session一致性方式 用户每一次请求都会...

WALK_MAN
今天
5
0
C++ yield()与sleep_for()

C++11 标准库提供了yield()和sleep_for()两个方法。 (1)std::this_thread::yield(): 线程调用该方法时,主动让出CPU,并且不参与CPU的本次调度,从而让其他线程有机会运行。在后续的调度周...

yepanl
今天
4
0
Java并发编程实战(chapter_3)(线程池ThreadPoolExecutor源码分析)

这个系列一直没再写,很多原因,中间经历了换工作,熟悉项目,熟悉新团队等等一系列的事情。并发课题对于Java来说是一个又重要又难的一大块,除非气定神闲、精力满满,否则我本身是不敢随便写...

心中的理想乡
今天
33
0
shell学习之获取用户的输入命令read

在运行脚本的时候,命令行参数是可以传入参数,还有就是在脚本运行过程中需要用户输入参数,比如你想要在脚本运行时问个问题,并等待运行脚本的人来回答。bash shell为此提 供了read命令。 ...

woshixin
今天
4
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部