Swagger2
1. Swagger 简介
Swagger是非常流行的API管理工具，支持整个API的生命周期，包括API设计、开发及测试。
2. 集成 Swagger2
2.1 添加依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
2.2 编写Swagger2配置类
@Configuration
@EnableSwagger2
public class Swagger2 {
// 控制开关
@Value("${swagger.show}")
private boolean swaggerShow;
public Docket createUserApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.greedy.web.task"))
.paths(PathSelectors.any())
.build()
.groupName("task")
.enable(swaggerShow);
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("STARK API")
.description("接口文档")
.termsOfServiceUrl("/")
.version("v1.0")
.build();
}
}
方法说明
- apiInfo()：指定接口文档的基本说明信息，例如：文档标题、文档描述、服务的URL、文档版本、作者、联系邮箱等等
- groupName()：为API设置分组名称
- select()：返回一个
ApiSelectorBuilder实例，用来控制哪些API接口可以暴露 - apis()：
ApiSelectorBuilder的成员方法，用来指定需要暴露的API所属的包 - paths()：
ApiSelectorBuilder的成员方法，用来过滤API路由路径 - build()：返回一个
Docket实例 - enable()：文档显示的控制开关
3. Swagger相关注解
(1) @Api 注解
作用在类上，用来描述Controller的作用，同一个Controller下的API作为一个分组
常用属性：
- value：URL的路径值
- tags：API分组标签，用来说明Controller的作用，如果设置了tags，则value会被覆盖
- description：API分组说明
(2) @ApiOperation 注解
作用在方法上，用来描述API接口
常用属性：
- value：API接口说明
(3) @ApiImplicitParam 注解
作用在方法上，用来描述单个参数的信息
常用属性：
- name：参数名
- value：参数中文描述
- required：是否必传
- defaultValue：参数默认值
- dataType：参数类型
(4) @ApiImplicitParams 注解
作用在方法上，用来描述多个参数的信息，属性类型为@ApiImplicitParam注解的数组
(5) @ApiIgnore 注解
作用在类上、方法上、参数上，用来忽略API接口或者接口的参数
(6) @ApiModel 注解
作用在JavaBean上，表示用对象来接收参数
常用属性：
- value：为模型提供备用名称
- descripton：为模型提供详细描述
(7) @ApiProperty 注解
作用在JavaBean的属性上，用来描述对象的字段
常用属性：
- name：属性名称
- value：属性中文描述
- dataType：属性的数据类型
