SpringBoot 学习（七）Swagger

7. Swagger

7.1 简介

便于前后端集成联调
RestFul Api 文档在线生成工具 ==> Api 文档与 Api 定义同步更新
直接运行，在线测试 Api 接口

7.2 springboot 集成 swagger

(1) 导入依赖

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>

(2) 集成 swagger

@Configuration
@EnableSwagger2 // 开启 swagger2
public class SwaggerConfig {
}

(3) swagger 页面信息

接口：localhost://8080/swagger-ui.html

在这里插入图片描述

(4) 配置 swagger 信息

@Configuration
@EnableSwagger2 // 开启 swagger2
public class SwaggerConfig {// 配置 Swagger Docket 的 bean 实例@Beanpublic Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());}// 配置 swagger api 信息private ApiInfo apiInfo() {// 作者信息Contact contact = new Contact("why", "https://gitee.com/", "1942953841@qq.com");return new ApiInfo("Why Swagger Api Info","Why so serious!!!","v1.0","https://gitee.com/",contact,"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList());}
}

(5) 配置 swagger 自定义扫描接口

// 多环境配置，注解方法
@PropertySource(value = "classpath:application.properties")
@Configuration
@EnableSwagger2 // 开启 swagger2
public class SwaggerConfig {// 配置 Swagger Docket 的 bean 实例@Beanpublic Docket docket(Environment environment) {// 多环境配置，java 方法// 设置要显示的 swagger 环境// Profiles profiles = Profiles.of("dev", "test");// 判断是否处在自己设定的环境中// boolean flag = environment.acceptsProfiles(profiles);return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())// enable 是否启用 swagger// .enable(flag).select()// RequestHandlerSelectors 配置扫描接口的方式// basePackage 指定要扫描的包// any() 扫描全部// none() 不扫描// withClassAnnotation 扫描类上的注解，参数是一个类上的反射对象// withMethodAnnotation 扫描方法上的注解.apis(RequestHandlerSelectors.basePackage("com.why.swagger.controller"))// paths 路径过滤// .paths(PathSelectors.ant("/why/**")).build();}
}

(6) 多文档分组配置

@Bean
public Docket docket1() {return new Docket(DocumentationType.SWAGGER_2).groupName("A");
}@Bean
public Docket docket2() {return new Docket(DocumentationType.SWAGGER_2).groupName("B");
}@Bean
public Docket docket3() {return new Docket(DocumentationType.SWAGGER_2).groupName("C");
}

(7) 注解的使用

实体类

/*** @ApiModel 用在类上，表示对类进行说明，用于实体类中的参数接收说明。*/
@ApiModel(value = "com.why.pojo.User", description = "用户类")
@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {/*** @ApiModelProperty() 用于字段，表示对 model 属性的说明。*/@ApiModelProperty("用户名")private String username;@ApiModelProperty("密码")private String password;
}

接口

/*** @Api 用在类上，说明该类的作用。* tags：接口说明，可以在页面中显示。*/
@Api(tags = "Hello 控制器类")
@RestController
public class HelloController {@ApiOperation("hello 方法")@GetMapping("/hello")public String hello() {return "hello";}/*** @ApiOperation 用在 Controller 里的方法上，说明方法的作用，每一个接口的定义。* value：接口名称* notes：详细说明*/@ApiOperation(value = "user 控制器", notes = "获取用户")/*** @ApiImplicitParams / @ApiImplicitParam 为单独的请求参数进行说明* name：参数名，对应方法中单独的参数名称。* value：参数中文说明。* required：是否必填。* paramType：参数类型，取值为 path、query、body、header、form。* dataType：参数数据类型。* defaultValue：默认值。*/@ApiImplicitParams({@ApiImplicitParam(name = "username", value = "用户名", dataType = "string", paramType = "query", required = true, defaultValue = "why"),@ApiImplicitParam(name = "password", value = "密码", dataType = "string", paramType = "query", required = true, defaultValue = "123")})/*** @ApiResponse 用于方法上，说明接口响应的一些信息；@ApiResponses 组装了多个 @ApiResponse。*/@ApiResponses({ @ApiResponse(code = 200, message = "OK", response = User.class) })@PostMapping(value = "/userObj")/*** @ApiParam 用于 Controller 中方法的参数说明。* value：参数说明* required：是否必填*/public User userObj(@ApiParam(value = "用户名", required = true) String username,@ApiParam(value = "密码", required = true) String password) {User user = new User(username, password);System.out.println(user);return user;}}

(8) 接口测试

swagger2 测试 get 接口不能传递参数，测试 post 接口可以传递参数

即含参接口使用 @PostMapping 和 @RequestMapping
swagger2 测试含参 @GetMapping 会报如下错误：

TypeError: Failed to execute ‘fetch‘ on ‘Window‘: Request with GET/HEAD method cannot have body.
效果
- Get 方法
- Post