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

时间  2019-11-25
标签 webapi 文档 好帮手 apidoc 使用 教程 繁體版
原文   原文链接

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

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

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

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

 

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

 

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

 

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

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

它能够对API的各类版本等级进行对比。因此不管是前端开发人员仍是你均可以追溯API版本的变化。
npm

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

使用步骤：

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.

Name Description
(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
 */

更多的手表版本示例。

相关文章
相关标签/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公众号
   欢迎关注本站公众号,获取更多信息
联系我们 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程