Api2Doc生成 Restful API 文档

1,引入maven

<dependency>
<groupId>com.github.terran4j</groupId>
<artifactId>terran4j-commons-api2doc</artifactId>
<version>1.0.2</version>
</dependency>

  2,

@Api2Doc 注解详述

Api2Doc 一共有 3 个注解:@Api2Doc、@ApiComment 及 @ApiError 。

@Api2Doc 用于对文档的生成进行控制。

@Api2Doc 修饰在类上,表示这个类会参与到文档生成过程中,Api2Doc 服务
会扫描 Spring 容器中所有的 Controller 类,只有类上有 @Api2Doc 的类,
才会被生成文档,一个类对应于文档页面左侧的一级菜单项,@Api2Doc 的 
name 属性则表示这个菜单项的名称。

@Api2Doc 也可以修饰在方法,不过在方法上的 @Api2Doc 通常是可以省略,
Api2Doc 服务会扫描这个类的所有带有 @RequestMapping 的方法,
每个这样的方法对应文档页面的左侧的二级菜单项, 菜单项的名称取 
@RequestMapping 的 name 属性,当然您仍然可以在方法上用 @Api2Doc 
的 name 属性进行重定义。

@ApiComment 注解详述

@ApiComment 用于对 API 进行说明,它可以修饰在很多地方:

  • 修饰在类上,表示对这组 API 接口进行说明;
  • 修饰在方法上,表示对这个 API 接口进行说明;
  • 修饰在参数上,表示对这个 API 接口的请求参数进行说明;
  • 修饰在返回类型的属性上,表示对这个 API 接口的返回字段进行说明;
  • 修饰在枚举项上,表示对枚举项进行说明;

如果相同名称、相同意义的属性或参数字段,其说明已经在别的地方定义过了,
可以用 @ApiComment 的 seeClass 属性表示采用指定类的同名字段上的说明信息

@ApiComment(seeClass = User.class)

@ApiError 注解详述

@ApiError 用于定义错误码,有的 API 方法在执行业务逻辑时会产生错误,
出错后会在返回报文包含错误码,以方便客户端根据错误码作进一步的处理,
因此也需要在 API 文档上体现错误码的说明。

@ApiError 的 value 属性表示错误码,comment 表示错误码的说明。

可以用 @Api2Doc 中的 order 属性给菜单项排序,order 的值越小,
该菜单项就越排在前面.

 
上一篇:Docker介绍以及Registry的安装 -摘自http://dockone.io/article/108


下一篇:用开源项目SwitchButton实现各种风格的switch