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

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

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

到此安装工作已经完成。

构建

配置(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

用法: @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
 */

更多手表版本示例

完整的例子

这是一个复杂的例子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
}
}

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏北京马哥教育

Linux Bash脚本15分钟进阶教程

这里的技术技巧最初是来自谷歌的“Testing on the Toilet” (TOTT)。这里是一个修订和扩增版本。

740
来自专栏CaiRui

Bash Shell 小试牛刀

一、终端打印 [root@cai ~]# echo welcome to bash! welcome to bash! [cairui@cai ~]$ echo...

1896
来自专栏Java学习之路

Java的LockSupport工具,Condition接口和ConditionObject LockSupportConditionConditionObject

在之前我们文章(关于多线程编程基础和同步器),我们就接触到了LockSupport工具和Condition接口,之前使用LockSupport工具来唤醒阻塞的线...

3635
来自专栏Scott_Mr 个人专栏

React Native 系列(一) -- JS入门知识

38410
来自专栏游戏杂谈

Node.js文件编码格式的转换

项目很多 lua 文件不是 utf-8格式,使用 EditPlus 查看的时候,显示为ASCII。还有的是带BOM的,带BOM倒好处理,之前写过,有一定规律。

2074
来自专栏C/C++基础

Linux命令(32)——grep命令

grep(Globally search a Regular Expression and Print)是GNU开发的一款免费开源的文本搜索工具。grep家族包...

1663
来自专栏dotnet & java

datatables 配套bootstrap样式使用小结(2) ajax篇

上一篇是介绍一下基本的用法,基本的原理是取出所有的数据,然后调用$.datatables(option)方法格式化,这种方法显然不太科学,所以ajax方式是必须...

1061
来自专栏aCloudDeveloper

总结:常用的通用数据处理指令

作者:bakari  时间:2012.4.21 1、 操作数类型 Imm立即操作数 Reg寄存器操作数 Mem内存操作数 2、 操作数寻址方式 立即数寻址 寄存...

2048
来自专栏PHP实战技术

Mysql字段类型设计相关问题!

Mysql是以文件存储在我们的系统的硬盘上面,那么

3028
来自专栏FreeBuf

Python黑客学习笔记:从HelloWorld到编写PoC(上)

本系列文章适合CS在读学生和万年工具党,本文会在英文原文的基础上做些修改,并适当增加些解释说明。 ? 本篇包含原文的前几部分: 0x0 – Getting St...

30710

扫码关注云+社区

领取腾讯云代金券