■一、Api2Doc
Api2Doc专注于RestfulAPI文档的自动生成，它的原理是通过反射，分析Controller中的信息生成文档。
■二、Api2Doc注解详述
Api2Doc一共有3个注解：@Api2Doc、@ApiComment及@ApiError。
| No | 注解 | 说明 | ||||||||||||||||||||||||||||
| 1 | @Api2Doc | ◆@Api2Doc用于对文档的生成进行控制。 ◆@Api2Doc修饰在类上，表示这个类会参与到文档生成过程中，Api2Doc服务会扫描Spring容器中所有的Controller类，只有类上有@Api2Doc的类，才会被生成文档，一个类对应于文档页面左侧的一级菜单项，@Api2Doc的name属性则表示这个菜单项的名称。 ◆@Api2Doc也可以修饰在方法，不过在方法上的@Api2Doc通常是可以省略，Api2Doc服务会扫描这个类的所有带有@RequestMapping的方法，每个这样的方法对应文档页面的左侧的二级菜单项，菜单项的名称取@RequestMapping的name属性，当然您仍然可以在方法上用@Api2Doc的name属性进行重定义。 |
||||||||||||||||||||||||||||
| 2 | @ApiComment | @ApiComment用于对API进行说明，它可以修饰在很多地方： 修饰在类上，表示对这组API接口进行说明。 修饰在方法上，表示对这个API接口进行说明。 修饰在参数上，表示对这个API接口的请求参数进行说明。 修饰在返回类型的属性上，表示对这个API接口的返回字段进行说明。 修饰在枚举项上，表示对枚举项进行说明。 如果相同名称、相同意义的属性或参数字段，其说明已经在别的地方定义过了， 可以用 @ApiComment 的 seeClass 属性表示采用指定类的同名字段上的说明信息。 |
||||||||||||||||||||||||||||
| 3 | @ApiError | @ApiError 用于定义错误码，有的 API 方法在执行业务逻辑时会产生错误， 出错后会在返回报文包含错误码，以方便客户端根据错误码作进一步的处理， 因此也需要在 API 文档上体现错误码的说明。 | ||||||||||||||||||||||||||||
■三、项目实例
1)项目结构
2)pom.xml
※需要引入terran4j-commons-api2doc。网上最新版本是1.0.4，但是这个版本目前下载不下来。可下载最新版本为1.0.2，对应这个版本的springboot版本为2.0.4-2.0.9。
3)启动类
※添加 @EnableApi2Doc 注解，以启用Api2Doc服务。
4)Controller类
5)实体类
6)生成API文档 http://localhost:8080/api2doc/home.html
■getUser
■updUser
