文档章节

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

吴伟祥
 吴伟祥
发布于 06/13 11:02
字数 4309
阅读 367
收藏 3
点赞 0
评论 0

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
}
}

© 著作权归作者所有

吴伟祥
粉丝 6
博文 209
码字总数 189825
作品 0
宝山
后端工程师
使用apidoc文档神器,快速生成api文档

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

jilei786 ⋅ 06/14 ⋅ 0

RESTFul接口测试工具:Wisdom RESTClient

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

niithub ⋅ 05/01 ⋅ 0

基于 Groovy 的 Web 框架 - Grails

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

匿名 ⋅ 2008/09/12 ⋅ 2

Sphinx将python代码注释生成文档

安装 使用pip进行安装: pip install sphinx 初始化 进入你代码所在的目录,输入: sphinx-quickstart 下图:PRD是代码所在目录,生成的文档保存目录设成doc 下图:设置项目名称与作者,项目名...

武耀文 ⋅ 2017/06/13 ⋅ 0

Redis 的 Java 客户端 - Jedis

Jedis 是 Redis 官方首选的 Java 客户端开发包。 实例方法: import redis.clients.jedis.* Jedis jedis = new Jedis("localhost");jedis.set("foo", "bar");String value = jedis.get("foo"......

匿名 ⋅ 2011/04/01 ⋅ 3

如何使用反射来分析PHP的数据结构

更准备的说是 如何用PHP分析类内部的结构。 介绍 当我开始学习PHP编程时,可能并不知道 的强大功能,主要原因是我不需要它来设计我的类,模块甚至是包等等,但是它在很多地方都有非常不错的能...

如来神掌 ⋅ 06/02 ⋅ 0

【ApiDoc】自动化导出接口文档之HTML/Markdown/PDF实践

本文主要参考 ApiDoc官方文档 最近项目开始接口测试,需要提供一份最新、最全的接口文档,也许你觉得没什么,但是如果我要求每个接口文档都要像下面的例子一样: 接口标题 接口描述 请求头参数...

liqingbiubiu ⋅ 2017/12/22 ⋅ 0

apidoc 生成Restful web Api文档

在项目开发过程中,总会牵扯到接口文档的设计与编写,之前使用的都是office工具,写一个文档,总也是不够漂亮和直观。好在git上的开源大神提供了生成文档的工具,so来介绍一下! 该工具是Nod...

油焖菠菜 ⋅ 2016/08/19 ⋅ 0

RESTful 风格 API 文档生成工具--apidoc-javadoc-generator

apidoc-javadoc-generator 一、项目介绍 apidoc是用node.js开发的可以根据api的注释文档生成相应的RESTful风格的api文档的工具,而且支持多种开发api的语言。 使用apidoc时生成文档时需要 3 ...

zerojump ⋅ 2017/10/05 ⋅ 0

API文档编写工具

从网络上检索到一些与API文档编写工具相关的资料,特记录如下: APIDoc 一个简单的RESTful API文档生成工具,主要是对代码中的注释来生成文档。开源,http://apidoc.tools prmd 根据JOSN样式...

OpenIoT ⋅ 2016/07/28 ⋅ 0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

Linux中的端口大全

1 被LANA定义的端口 端口 名称 描述 1 tcpmux TCP 端口服务多路复用 5 rje 远程作业入口 7 echo Echo 服务 9 discard 用于连接测试的空服务 11 systat 用于列举连接了的端口的系统状态 13 d...

寰宇01 ⋅ 16分钟前 ⋅ 0

Confluence 6 如何备份存储文件和页面信息

备份的 ZIP 文件包含有 entities.xml,这个 XML 文件包含有 Confluence 的所有页面内容和存储附件的目录。 备份 Zip 文件结构 页面的附件是存储在附件存储目录中的,通过页面和附件 ID 进行识...

honeymose ⋅ 18分钟前 ⋅ 0

【每天一个JQuery特效】根据状态确定是否滑入或滑出被选元素

主要效果: 本文主要采用slideToggle()方法实现以一行代码同时实现以展开或收缩的方式显示或隐藏被选元素。 主要代码如下: <!DOCTYPE html><html><head><meta charset="UTF-8">...

Rhymo-Wu ⋅ 22分钟前 ⋅ 0

度量.net framework 迁移到.net core的工作量

把现有的.net framework程序迁移到.net core上,是一个非常复杂的工作,特别是一些API在两个平台上还不能同时支持。两个类库的差异性,通过人工很难识别全。好在微软的工程师们考虑到了我们顾...

李朝强 ⋅ 27分钟前 ⋅ 0

请不要在“微服务”的狂热中迷失自我!

微服务在过去几年一直是一个非常热门的话题(附录1)。何为“微服务的疯狂”,举个例子: 众所周知,Netflix在DevOps上的表现非常棒。Netfix可以做微服务。因此:如果我做微服务,我也将非常...

harries ⋅ 29分钟前 ⋅ 0

oAuth2 升级Spring Cloud Finchley.RELEASE踩坑分享

背景 6.19号,spring团队发布了期待已久的 Spring Cloud Finchley.RELEASE 版本。 重要变化: 基于Spring Boot 2.0.X 不兼容 Spring Boot 1.5.X 期间踩过几个坑,分享出来给大伙,主要是关于...

冷冷gg ⋅ 58分钟前 ⋅ 0

OSChina 周一乱弹 —— 理发师小姐姐的魔法

Osc乱弹歌单(2018)请戳(这里) 【今日歌曲】 @冰冰棒- :分享田馥甄的单曲《My Love》 《My Love》- 田馥甄 手机党少年们想听歌,请使劲儿戳(这里) @Li-Wang :哎,头发又长了。。。又要...

小小编辑 ⋅ 今天 ⋅ 8

Kafka1.0.X_消费者API详解2

偏移量由消费者管理 kafka Consumer Api还提供了自己存储offset的功能,将offset和data做到原子性,可以让消费具有Exactly Once 的语义,比kafka默认的At-least Once更强大 消费者从指定分区...

特拉仔 ⋅ 今天 ⋅ 0

NEO智能合约之发布和升级(二)

接NEO智能合约之发布和升级(一),我们接下来说说智能合约的升级功能。 一 准备工作 合约的升级需要在合约内预先设置好升级接口,以方便在升级时调用。接下来我们对NEO智能合约之发布和升级...

红烧飞鱼 ⋅ 今天 ⋅ 0

个人博客的运营模式能否学习TMALL天猫质量为上?

心情随笔|个人博客的运营模式能否学习TMALL天猫质量为上? 中国的互联网已经发展了很多年了,记得在十年前,个人博客十分流行,大量的人都在写博客,而且质量还不错,很多高质量的文章都是在...

原创小博客 ⋅ 今天 ⋅ 0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

返回顶部
顶部