apidoc的介绍和使用

来源：互联网发布：淘宝被骗了编辑：程序博客网时间：2024/05/17 08:03

github apidoc demo

apidoc展示效果

入门

前言

本文档中的所有示例使用Javadoc样式（可以在C＃中使用，围棋，飞镖，Java和JavaScript的，PHP，打字稿和所有其他的Javadoc能够语言）：

/** * This is a comment. */

对于其他语言使用自己特有的多行注释代码：

的CoffeeScript

###This is a comment.###

Elixir

@apidoc """This is a comment."""

Erlang (% within the comment is optional)

%{% This is a comment.%}

Perl的（Doxygen的）

#**# This is a comment.#*

Python

"""This is a comment."""

Ruby

=beginThis is a comment.=end

安装

npm install apidoc -g

跑

apidoc -i myapp/ -o apidoc/ -t mytemplate/

创建目录中的所有文件的apiDoc myapp/，使用从目录模板mytemplate/，并把所有输出目录apidoc/。

不带任何参数，apiDoc生成全部的文档.cs .dart .erl .go .java .js .php .py .rb .ts文件，在当前目录（包括子目录）和输出写入./doc/。

命令行界面

显示命令行参数：

apidoc -h

重要参数：

参数描述-f，--file过滤器正则表达式过滤来选择应该被解析（多-f可以使用）的文件。默认情况下.cs .dart .erl .go .java .js .php .py .rb .ts，

示例（仅解析和名为.js文件.TS）：
apidoc -f ".*\\.js$" -f ".*\\.ts$"-i，--input输入/源目录名。。您的项目文件的位置

示例：
apidoc -i myapp/-o，--output输出目录名。位置放在哪里来生成文档。

例如：
apidoc -o apidoc/-t，--template使用模板输出文件。您可以创建和使用自己的模板。

例如：
apidoc -t mytemplate/

咕噜模块

一个单独的模块咕噜支持，请访问github.com/apidoc/grunt-apidoc
或通过NPM安装：

npm install grunt-apidoc --save-dev

模板

apiDoc包括使用缺省模板车把，自举，RequireJS和jQuery的所生成的输出api_data.js并且api_project.js作为一个HTML页。

默认生成apiDoc使用复杂的模板，其支持

版本：查看不同版本的API的
比较：您的API的两个版本之间的变化看法

查看默认的演示

创建您自己的

您可以创建自己的模板，并使用apiDoc生成的文件api_data.js，api_project.js或只JSON文件api_data.json，api_project.json。

查看源https://github.com/apidoc/apidoc/tree/master/template

延伸

apiDoc可以用自己的参数进行扩展（如果有些东西不可用，你需要）。看的lib /解析器/， LIB /工人/，和LIB /解析器/ 目录中apidoc / apidoc核心中的示例项目。 parser分割参数数据，worker处理所有的数据发现，附加功能和filter数据减少所需的东西。

用法示例： apidoc --parse-filters myFilter=pathToMyFilter/myFilter.js

或叉整个项目，并创建一个pull请求做出apiDoc更好。

配置（apidoc.json）

可选apidoc.json在项目的根目录包含有关项目如标题，简短描述，版本和类似配置选项通用信息页眉/页脚设置或模板的特定选项。

apidoc.json

{  "name": "example",  "version": "0.1.0",  "description": "apiDoc basic example",  "title": "Custom apiDoc browser title",  "url" : "https://api.github.com/v1"}

如果您使用package.json（在Node.js的项目如），所有apidoc.json设置都可以在做package.json太多，只是增加他们的下"apidoc": { }参数。

的package.json

{  "name": "example",  "version": "0.1.0",  "description": "apiDoc basic example",  "apidoc": {    "title": "Custom apiDoc browser title",    "url" : "https://api.github.com/v1"  }}

对于apidoc.json设置

名称描述名称项目的名称。
如果没有apidoc.json与字段存在，则apiDoc尝试，以确定从所述值package.json。版项目的版本。
如果没有apidoc.json与字段存在，则apiDoc尝试，以确定从所述值package.json。描述项目简介。
如果没有apidoc.json与字段存在，则apiDoc尝试，以确定从所述值package.json。标题浏览器的标题文字。网址前缀API路（终点），例如： https://api.github.com/v1SAMPLEURL如果设置，窗体来测试API方法（发送请求）将是可见的。见@apiSampleRequest了解更多详情。头标题导览文本所包含header.md文件。
（看页眉/页脚）文件名文件名（降价文件）所包含的header.md文件。页脚标题导览文本所包含footer.md文件。文件名文件名（降价文件）所包含的footer.md文件。订购订购输出API-名/组名称的列表。未定义名称会自动显示上次。

"order": [  "Error",  "Define",  "PostTitleAndError",  "PostError"]

模板的具体设置

以下设置特定于apiDoc的默认模板。

名称类型描述模板 forceLanguage串禁用浏览器语言自动检测并设置特定的语言环境。
例如：de，en。
查看可用区域设置在这里。 withCompare布尔启用与旧的API版本比较。默认：true withGenerator布尔在输出页脚中产生的信息。默认：true jQueryAjaxSetup目的设为默认值的Ajax请求。

页眉页脚

在你的项目apidoc.json，你可以添加页眉和页脚。

标题将在导航中可见。文件名应该是一个文本文件降价。

apidoc.json

{  "header": {    "title": "My own header title",    "filename": "header.md"  },  "footer": {    "title": "My own footer title",    "filename": "footer.md"  }}

例子

介绍演示用一个小例子可以发现speakerdeck.com。

基本

在这个基本的例子，我们有一个小项目文件和apidoc.json。

查看示例输出

apidoc.json

{  "name": "example",  "version": "0.1.0",  "description": "A basic apiDoc example"}

从apidoc.jsonapiDoc获得项目的名称，版本和说明。
该文件optional（这取决于你的模板，如果需要对数据）。

example.js

/** * @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" *     } * * @apiError UserNotFound The id of the User was not found. * * @apiErrorExample Error-Response: *     HTTP/1.1 404 Not Found *     { *       "error": "UserNotFound" *     } */

一个文档块开头/**和结尾*/。

本例介绍一个GET方法来请求用户的用户信息id。

@api {get} /user/:id Request User information是必需的，没有@apiapiDoc忽略一个文档块。

@apiName是一个unique名称，应始终使用。
格式：法 + 路径（如获取+用户）

@apiGroup 应始终使用，根据该名称将这个方法进行分组。

所有其他字段都是可选的，看看在他们的描述apiDoc-PARAMS。

继承

继承的意思是，你可以定义你的文档，应多次使用的部分。

查看示例输出

apidoc.json

{  "name": "example-inherit",  "version": "0.1.0",  "description": "apiDoc inherit example"}

example.js

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

在这种情况下，一个命名块UserNotFoundError与定义@apiDefine。
也就是说块可以与使用多次@apiUse UserNotFoundError。

在所产生的输出，这两种方法GET and PUT将具有完整UserNotFoundError文档。

继承定义的命令是apiDefine，
使用的名字是apiUse， apiGroup并且apiPermission是使用命令，但在他们的背景下，不能继承参数，只有标题和描述（结合apiVersion）。

Inheritation只适用于1父，多层次将使内嵌代码不可读和变化非常复杂。

版本

不错的功能是以前定义的文件块的保持。这使得它能够比较一个方法的版本与它的前身。前端开发者可以简单地这样看什么已经改变和修改他们的代码。

查看示例输出

在这个例子中，单击选择框（主版），并选择右上角Compare all with predecessor。

主要的航标一切都改变了方法，用绿色吧。
每种方法示区别，它的前身。
添加的绿色标志的内容（在这种情况下，标题的文本改变和字段registered中加入）。
被删除的红色标记的内容。

您可以更改主版（右上）到以前的版本，并同他们的前任老方法。

apidoc.json

{  "name": "example-versioning",  "version": "0.2.0",  "description": "apiDoc versioning example"}

使你的代码与文档块吹出来的，我更喜欢使用一个单独的名为历史文件_apidoc.js。在您更改文档块，旧块复制到这个文件，仅此而已。

_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每一个文档块上。

版本可以每块上使用，也继承块。你不必自动改变一个继承块上的版本，解析器检查为最近的前身。

完整的示例（一起）

这是一个复杂的例子inherit，versioning文件，历史文件_apidoc.js，解释是在代码和生成的文档。

查看示例输出

文件：

_apidoc.js
example.js
apidoc.json

apiDoc-PARAMS

结构参数，如：

@apiDefine

用于定义一个文档块为草稿。该草案可以包含在正常的API文档块。有了草稿可以单独复杂的或复发的块。

已定义的块可以拥有所有PARAMS（像@apiParam），除其他定义的块。

@api

@api {method} path [title]

需要！

如果没有这个指标，apiDoc解析器忽略文档块。

除了定义块一样@apiDefine，它们并不需要@api。

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

名称描述方法申请方法名称：DELETE，GET，POST，PUT，...
更多信息维基百科的HTTP Request_methods路径请求路径。标题可选一个简短的标题。（用于导航和文章标题）

例：

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

@apiDefine

@apiDefine name [title]                     [description]

定义为在使用的草案的允许@api块或类似的API函数@apiPermission。

@apiDefine 只能每块使用一次

有了@apiUse一个定义的块将被导入，或名称的标题和描述将被使用。

用法： @apiDefine MyError

名称描述名称为块/值唯一的名字。
用不同的名字相同@apiVersion可以被定义。标题可选一个简短的标题。仅用于像命名函数@apiPermission或@apiParam (name)。说明可选在下一行详细说明的开始，可以使用多行。仅用于像命名函数@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 */

欲了解更多的手表继承的例子。

@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

名称描述（集团）可选所有参数将被这个名字进行分类。
如果没有一个组，默认的Error 4xx设置，
可以设置标题和描述与@apiDefine。{}型可选返回类型，例如{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.

名称描述类型可选响应格式。标题可选简短标题的例子。例详细的例子，多线能力。

例：

/** * @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标头如为授权的参数。

类似的操作，@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

名称描述名称该方法的唯一名称。用不同的名称相同@apiVersion，可以定义
格式：法 + 路径（如获取+用户），只有一个建议，只要你想，你可以命名。
也用作导航称号。

例：

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

@apiParam

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

描述传递给您的API-方法的参数。

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

名称描述（集团）可选所有参数将被这个名字进行分类。
如果没有一个组，默认的Parameter设置，
可以设置标题和描述与@apiDefine。{}型可选参数类型，例如{Boolean}，{Number}，{String}，{Object}，{String[]}（字符串数组），...{{型大小}}可选关于变量的大小的信息。
{string{..5}}具有最多5个字符的字符串。
{string{2..5}}具有最小字符串。2个字符和最大字符5，
{number{100-999}}在100和999之间的数字。{类型= ALLOWEDVALUES}可选关于变量的允许值的信息。
{string="small"}只能包含单词“小”（一个常数）。一个字符串
{string="small","huge"}，它可以包含词语“小”或“大”。字符串
{number=1,2,3,99}一批具有的1允许值，2，3 99

：可与大小组合
{string {..5}="small","huge"}有最多5个字符，只包含单词串“小”或“庞大”。领域变量名。[领域]字段名用方括号将变量定义为可选的。=设置defaultValue可选该参数的默认值。说明可选字段的描述。

例子：

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

@apiSampleRequest

@apiSampleRequest url

与apidoc.json配置参数一起使用此参数SAMPLEURL。

如果sampleUrl被设置，所有的方法将有API测试形式（从端点@api将被追加）。
如果没有SAMPLEURL只与方法@apiSampleRequest将有一个表格。

如果@apiSampleRequest url在方法块设置，这个网址将被用于请求（它将覆盖SAMPLEURL当它以http开头）。

如果sampleUrl已设置，你不想与测试形式的方法，然后添加@apiSampleRequest off到文档块。

用法： @apiSampleRequest http://test.github.com

名称描述网址URL到您的测试API服务器。

覆盖的配置参数SAMPLEURL并追加@api网址：
@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~~V
它覆盖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~~V
它扩展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~~V
它激活仅此法的要求，因为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.

名称描述（集团）可选所有参数将被这个名字进行分类。
如果没有一个组，默认的Success 200设置，
可以设置标题和描述与@apiDefine。{}型可选返回类型，例如{Boolean}， {Number}， {String}，{Object}，{String[]}（字符串数组），...领域返回标识符（返回成功代码）。说明可选字段的描述。

例：

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

示例使用Array：

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

名称描述版支持简单的版本（major.minor.patch）。有关更多信息语义版本规格（SemVer）。

例：

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

欲了解更多的手表版本的例子。

0 0