webApi文档好帮手-apidoc使用教程

apidoc官网 ： http://apidocjs.com/

apidoc工具说明： http://apidoc.tools/

在开发后台接口的过程中，我们肯定要提供一份api接口文档给终端app。

目前大多数的app的接口请求应该都是http+json的方式。 但是一直苦于做不出份漂亮的api文档，用word写，也太丑了。。怎么才能做出一份像腾讯、新浪微博等各种开放api平台那样漂亮的api文档呢？找了好久发现了今天的主角-apidoc。

 

官网地址：http://apidocjs.com

 

开放API已经成为当下主流平台的一个要素，特别对于社交、电商类的平台开放API更成为了竞争力的一种。开放API文档的完整性、可阅读性往往影响着接入方是否能顺利地、快速地接入到平台，一份好的、统一的API文档也是开放平台不可或缺的要素。

 

apidoc是通过源码中的注释来生成API文档，所以只要识别兼容现今大部分流行语言的注释方法便达到了兼容语言的效果。

有了它，我们只需要在写源码的时候顺手写上一些简单的注释，就可以生成出漂亮的文档了（当然，有同学会问文档不是先定义的吗？你把接口的源码声明好不就ok啦？或者你写点其他的语言也行啊。。  最简单的就是学习下javascript，只要学会怎么创建js文件，然后怎么声明function，给function添加注释即可，实在写不了源码，写一个简单的js文件，然后用apidoc生成一下就出文档了。大笑）。

它可以对API的各种版本等级进行对比。所以无论是前端开发人员还是你都可以追溯API版本的变化。

支持多种语言：C#, Go, Dart, Java, JavaScript, PHP, TypeScript (all DocStyle capable languages)，CoffeeScript，Erlang，Perl，Python，Ruby。

使用步骤：

1.安装nodejs。去http://www.nodejs.org/下载安装一个nodejs；

2.安装apidoc：命令行输入：npm install apidoc -g    貌似是在线安装的，稍等一下即可。

3. 准备一个目录myapp，下面放源码文件，源码文件中要按照apidoc的规范写好注释。具体规范参见官网，我这里就不翻译了。

例如我写java的源码：

/** 
 * 此接口不要去实现，仅作为输出api文档用的 
 * @author xumin 
 * 
 */  
@Deprecated  
public interface ApiDoc {  
    /** 
     *  
     * @api {get} /company/list 获取公司信息 
     * @apiName 获取公司列表 
     * @apiGroup All 
     * @apiVersion 0.1.0 
     * @apiDescription 接口详细描述 
     *  
     * @apiParam {int} pageNum分页大小  
     *  
     * @apiSuccess {String} code 结果码 
     * @apiSuccess {String} msg 消息说明 
     * @apiSuccess {Object} data 分页数据封装 
     * @apiSuccess {int} data.count 总记录数 
     * @apiSuccess {Object[]} data.list 分页数据对象数组 
     * @apiSuccessExample Success-Response: 
     *  HTTP/1.1 200 OK 
     * { 
     * code:0, 
     * msg:'success', 
     * data:{} 
     *  } 
     *   
     *  @apiError All 对应<code>id</code>的用户没找到 asdfasdf  
     *  @apiErrorExample {json} Error-Response: 
     *  HTTP/1.1 404 Not Found 
     *  { 
     *   code:1, 
     *   msg:'user not found', 
     *   } 
     *    
     * @param param 
     * @return 
     * @throws Exception 
     */  
    void a();  
}

4. 生成api文档。

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

myapp是当前工作目录下的源码目录

apidoc是用于存放生成出的文档文件的目录

mytemplate是自定义模板文件夹，刚开始用，可以不指定，后面有需要了再研究怎么自定义模板吧。

 

如果看到“success: Done.”说明生成成功 ，到 apidoc目录下打开index.html查看生成的文档.

大功告成！

 

apiDoc-Params

结构参数如：

  • @apiDefine

用于定义可重用的文档块。 此块可以包含在正常的api文档块中。 使用@apiDefine可以更好地组织复杂的文档，并避免复制循环块。

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

 

@api

@api {method} path [title]

需要！

没有该指标，apiDoc解析器忽略文档块。

唯一的例外是由@apiDefine定义的文档块，它们不需要@api。

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

名称说明
method 请求方式名称: DELETE, GET, POST, PUT, ...
跟多请参考 Wikipedia HTTP-Request_methods
path 请求地址
titleoptional 一个简短的标题。 （用于导航和文章标题）

示例:

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

@apiDefine

@apiDefine name [title]
                     [description]

定义要嵌入在@api块中的文档块或者像@apiPermission这样的api函数。

@apiDefine只能在每个块中使用一次

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

用法: @apiDefine MyError

名称说明
name 块/值的唯一名称。
可以定义与不同@apiVersion相同的名称。
titleoptional 一个简短的标题。 只用于@apiPermission或@apiParam（name）等命名函数。
descriptionoptional 详细说明从下一行开始，可以使用多行。 仅用于像@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.

名称说明
text 多线描述文字。

示例:

/**
 * @apiDescription This is the Description.
 * It is multiline capable.
 *
 * Last line of Description.
 */

@apiError

@apiError [(group)] [{type}] field [description]

错误返回参数。

用法: @apiError UserNotFound

名称说明
(group)optional 所有参数将按此名称分组。
没有组，默认错误4xx被设置。
您可以使用@apiDefine设置标题和说明。
{type}optional 返回类型，例如 {Boolean}，{Number}，{String}，{Object}，{String []}（字符串数组），...
field 返回标识符（返回的错误代码）。
descriptionoptional 说明字段。

示例:

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

名称说明
typeoptional 响应格式。
titleoptional 示例的简称。
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.

名称说明
typeoptional 代码语言
title 示例的简称。
example 详细的例子，多线程能力。

示例:

/**
 * @api {get} /user/:id
 * @apiExample {curl} Example usage:
 *     curl -i http://localhost/user/4711
 */

@apiGroup

@apiGroup name

应该永远使用

定义方法文档块所属的组。 组将用于生成的输出中的主导航。 结构定义不需要@apiGroup。

用法: @apiGroup User

名称说明
name 组名称 也用作导航标题。

示例:

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

@apiHeader

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

描述传递给您的API参数 授权。

类似于@apiParam的操作，只有输出是上面的参数。

用法: @apiHeader (MyHeaderGroup) {String} authorization Authorization value.

名称说明
(group)optional 所有参数将按此名称分组。
没有组，默认参数被设置。
您可以使用@apiDefine设置标题和说明。
{type}optional 参数类型，例如 {Boolean}，{Number}，{String}，{Object}，{String []}（字符串数组），...
field 变量名。
[field] 带有括号的字段名将“变量”定义为可选项。
=defaultValueoptional 参数默认值。
descriptionoptional 说明字段。

示例:

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

名称说明
typeoptional 请求格式。
titleoptional 示例的简称。
example 详细的例子，多线程能力。

示例:

/**
 * @api {get} /user/:id
 * @apiHeaderExample {json} Header-Example:
 *     {
 *       "Accept-Encoding": "Accept-Encoding: gzip, deflate"
 *     }
 */

@apiIgnore

@apiIgnore [hint]

将其放在块的顶部。

@apiIgnore的块不会被解析。 如果您在源代码中留下过时或未完成的方法，并且不想将其发布到文档中，这是非常有用的。

用法: @apiIgnore Not finished Method

名称说明
hintoptional 为什么这个块应该被忽略的简短信息。

示例:

/**
 * @apiIgnore Not finished Method
 * @api {get} /user/:id
 */

@apiName

@apiName name

应该永远使用

定义方法文档块的名称。 名称将用于生成输出中的子导航。 结构定义不需要@apiName。

用法: @apiName GetUser

名称说明
name 方法的唯一名称。 可以定义与不同@apiVersion相同的名称。

格式：方法+路径（例如Get + User），只有一个提案，您可以按需要命名。
也用作导航标题。

示例:

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

@apiParam

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

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

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

NameDescription
(group)optional 所有参数将按此名称分组。
没有组，默认参数被设置。
您可以使用@apiDefine设置标题和说明。
{type}optional 参数类型，例如 {Boolean}，{Number}，{String}，{Object}，{String []}（字符串数组），...
{type{size}}optional

关于变量大小的信息。
{string {.. 5}}一个最多5个字符的字符串。
{string {2..5}}一个最小的字符串。 2个字符和最多5个字符。
{number {100-999}}一个介于100和999之间的数字。
{type=allowedValues}optional

关于变量允许值的信息。
{string =“small”}一个只能包含单词“small”（一个常量）的字符串。
{string =“small”，“huge”}一个可以包含单词“small”或“huge”的字符串。
{number = 1,2,3,99}一个允许值为1,2,3和99的数字。

可以结合尺寸：
{string {..5} =“small”，“huge”}一个字符串，最多5个字符，只包含“小”或“巨”字样。
field 变量名。
[field] 带有括号的字段名将“变量”定义为可选项。
=defaultValueoptional 参数默认值。
descriptionoptional 说明字段。

示例:

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

名称说明
typeoptional 请求格式。
titleoptional 示例的简称。
example 详细的例子，多线程能力。

示例:

/**
 * @api {get} /user/:id
 * @apiParamExample {json} Request-Example:
 *     {
 *       "id": 4711
 *     }
 */

@apiPermission

@apiPermission name

输出权限名称。 如果使用@apiDefine定义名称，则生成的文档将包含附加的标题和说明。

用法: @apiPermission admin

名称说明
name 唯一的权限名称。

示例:

/**
 * @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开头时，该url将覆盖sampleUrl）。

如果设置了sampleUrl，并且不想使用带有测试表单的方法，那么将@apiSampleRequest添加到文档块中。

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

名称说明
url

URL到您的测试api服务器。

覆盖配置参数sampleUrl并附加@api url：
@apiSampleRequest http://www.example.com

前缀@api url：
@apiSampleRequest / my_test_path

如果配置参数sampleUrl被设置，禁用api测试：
@apiSampleRequest关闭

示例:

这将发送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)optional

所有参数将按此名称分组。
没有组，默认的成功200被设置。
您可以使用@apiDefine设置标题和说明。
{type}optional 返回类型，例如 {Boolean}，{Number}，{String}，{Object}，{String []}（字符串数组），...
field 返回标识符（返回的成功代码）。
descriptionoptional 说明字段。

示例:

/**
 * @api {get} /user/:id
 * @apiSuccess {String} firstname Firstname of the User.
 * @apiSuccess {String} lastname  Lastname of the User.
 */

（组）的示例，@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" }

名称说明
typeoptional 响应格式。
titleoptional 示例的简称。
example 详细的例子，多线程能力。

示例:

/**
 * @api {get} /user/:id
 * @apiSuccessExample {json} Success-Response:
 *     HTTP/1.1 200 OK
 *     {
 *       "firstname": "John",
 *       "lastname": "Doe"
 *     }
 */

@apiUse

@apiUse name

包含一个@apiDefine定义的块。 如果与@apiVersion一起使用，将包含相同或最近的前身。

用法: @apiUse MySuccess

名称说明
name 定义块的名称。

示例:

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

更多的手表版本示例。

posted @ 2017-09-18 14:44  jiangxiaobo  阅读(6225)  评论(0)  编辑  收藏  举报