Swagger基础入门整合SpringBoot
一、概述
Swagger是一个接口文档工具，提供接口文档的自动生成和测试的工具。
致力于解决接口规范化、标准化、文档化的开源库，一款真正的开发神器。
它能够自动生成接口文档和客户端服务端代码，做到代码和接口的一致性，让我们花精力去修改接口文档。
二、入门案例
先把例子跑起来，再回头理解代码。
使用环境或技术：
- SpringBoot 2.4.5
1、maven导入依赖文件
io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
2、写一个配置类（代码有注释说明）
/**
* @author Hacah
* @date 2021/5/12 11:00
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket productApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 配置是否启动swagger,默认为true
.enable(true)
.select()
/**
* apis():指定扫描的接口
* RequestHandlerSelectors:配置要扫描接口的方式
* basePackage:指定要扫描的包
* any:扫面全部
* none:不扫描
* withClassAnnotation:扫描类上的注解(参数是类上注解的class对象)
* withMethodAnnotation:扫描方法上的注解(参数是方法上的注解的class对象)
*/
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
/**
* paths():过滤路径
* PathSelectors:配置过滤的路径
* any:过滤全部路径
* none:不过滤路径
* ant:过滤指定路径:按照按照Spring的AntPathMatcher提供的match方法进行匹配
* regex:过滤指定路径:按照String的matches方法进行匹配
*/
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("swagger和springBoot整合")
.description("swagger和SpringBoot整合")
.version("1.0.0.0").build();
}
}
3、编写一个RestController，添加@ApiOperation注解
@ApiOperation(value = "hello")
@RequestMapping("/hello")
public String hello() {
return "Hello World!";
}
4、启动项目，打开地址localhost:8080/swagger-ui.html
解释：
@ApiOperatio：作用方法上，说明该接口干嘛的。
.select().apis.paths.build是组合使用的
三、常用注解或操作
1、文档分组
- 设置组名，在创建Docket时，执行groupName操作
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//配置Swagger信息
.groupName("zsr")
...
- 创建多个Docket对象，指定组名就有多个组了
2、实体类注解
-
@ApiModel为类添加注释，说明是什么类。 -
@ApiModelProperty为类属性添加注释，说明是什么属性。
例如：
@ApiModel(value = "条件类", description = "存储请求过来的查询条件和内容和分页信息")
@Data
public class PageVO {
@ApiModelProperty(value = "查询条件")
private List queryCondition;
@ApiModelProperty(value = "查询内容")
private String queryContent;
@ApiModelProperty(value = "页号")
private Integer pageNum = 1;
@ApiModelProperty(value = "每页显示数量")
private Integer pageSize = 20;
结果如下
3、不同环境下是否启动文档
我们有时方便完成一个项目，分多个配置文件，有dev，test，prod等，分别代表开发，测试，生产环境。在生产环境我们并不希望开启文档。
1、先有三个配置文件，在主配置文件启用dev配置文件
2、在配置类中添加
// 可运行文档的环境
Profiles profiles = Profiles.of("dev", "test");
// 返回是否包含运行环境的判断值
boolean b = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 配置是否启动swagger,默认为true
.enable(b)
...
3、如果在主配置文件启动prod就不会启动文档，无法访问地址
4、常用注解
Api
作用类上，说明类的作用
@Api(tags = {"页面数据接口"})
@RestController
public class PageController
ApiParam
作用于方法中的参数，说明参数的作用
public String findTableData(@ApiParam(name = "查询条件") @RequestBody PageVO pageVO)
ApiResponse 和 ApiResponses
ApiResponse作用于方法上，说明响应的信息。ApiResponses可包含多个ApiResponse
@ApiResponses({@ApiResponse(code = 200, message = "ok", response = ResultVo.class)})
@RequestMapping({"/page1"})
public String findTableData(@RequestBody PageVO pageVO) {
ApiImplicitParam 和 ApiImplicitParams
ApiImplicitParam作用于方法上，表示单独说明请求参数。ApiImplicitParams表示一组请求的参数
@ApiImplicitParams(@ApiImplicitParam(name = "pageVo", value = "查询参数"))