SpringBoot2整合Swagger2-plus
Posted feixiong1688
tags:
篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了SpringBoot2整合Swagger2-plus相关的知识，希望对你有一定的参考价值。
目录
一.整合swagger2
1. 加依赖
<!-- 引入swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
2. 写配置
swagger配置类
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(
// RequestHandlerSelectors.any() // 所有都暴露
RequestHandlerSelectors.basePackage("xx.xx") // 指定包位置
)
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("spring boot示例接口API")
.description("spring boot示例接口API")
.version("1.0.0")
.build();
}
}
WebMvc中加入配置
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
PS: 如果使用的是SpringBoot2最好实现WebMvcConfigurer, 如果采用的是继承WebMvcConfigurationSupport, 需加入@EnableWebMvc.下一篇笔记会详解SpringMVC的配置
3. 常用注解：
- @Api()用于类；
表示标识这个类是swagger的资源
- @ApiOperation()用于方法；
表示一个http请求的操作
- @ApiParam()用于方法，参数，字段说明；
表示对参数的添加元数据（说明或是否必填等）
- @ApiModel()用于类
表示对类进行说明，用于参数用实体类接收
- @ApiModelProperty()用于方法，字段
表示对model属性的说明或者数据操作更改
- @ApiIgnore()用于类，方法，方法参数
表示这个方法或者类被忽略
- @ApiImplicitParam() 用于方法
表示单独的请求参数
- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam
4. 演示demo
@SpringBootApplication
@RestController
@Api(tags = "测试")
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class, args);
}
@PostMapping("/insert")
@ApiOperation(value = "新增用户", httpMethod = "POST")
public User insert(@RequestBody User user) {
user.setId(UUID.randomUUID().toString());
return user;
}
@GetMapping("/by-id/{id}")
@ApiOperation(value = "根据id查询用户", httpMethod = "GET")
public User insert(@PathVariable String id) {
User user = new User();
user.setUsername("test");
user.setPassword("123");
user.setAge(20);
return user;
}
@PostMapping("/login")
@ApiOperation(value = "登陆", httpMethod = "POST")
public User login(@RequestBody User user) {
user.setId(UUID.randomUUID().toString());
return user;
}
@Data
@ApiModel("用户对象")
static class User {
@ApiModelProperty("id")
private String id;
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("密码")
private String password;
@ApiModelProperty("年龄")
private int age;
@ApiModelProperty("性别")
private int sex;
@ApiModelProperty("真实姓名")
private String realName;
@ApiModelProperty("地址")
private String address;
}
}
5. 实际效果
查询
新增
登录
可以看到在查询的时候没多大问题, 但是新增时用户ID一般是后台生成, 登录的话也只需要用户名和密码. 显示过多的参数会导致文档冗余.前后端分立后也会造成不知道具体传参的困扰,那swagger的作用就大打折扣
二. 整合swagger2-plus
针对上诉问题的产生, 就引出了今天的主角swagger2-plus, 有了这个工具我们就可以对参数进行分组, 解决上述问题.
1. 加依赖
<!-- 引入swagger2-plus -->
<dependency>
<groupId>cn.weiguangfu</groupId>
<artifactId>springfox-swagger2-plus</artifactId>
<version>2.9.2-1-beta2</version>
</dependency>
swagger2依赖可以删除, 有这个依赖就行
2. 写配置
@Configuration
//@EnableSwagger2
@EnableSwagger2Plus
public class SwaggerConfig {
注释掉@EnableSwagger2改成@EnableSwagger2Plus
swagger.push.enable=true
配置文件中加入以上代码
3. 实际应用
加入参数分组类
public class SwaggerGroups {
public static class Insert {};
public static class Login{};
}
将对象参数用@ApiRequestInclude分组类
@Data
@ApiModel("用户对象")
static class User {
@ApiModelProperty("id")
private String id;
@ApiModelProperty("用户名")
@ApiRequestInclude(groups = {SwaggerGroups.Insert.class, SwaggerGroups.Login.class})
private String username;
@ApiModelProperty("密码")
@ApiRequestInclude(groups = {SwaggerGroups.Insert.class, SwaggerGroups.Login.class})
private String password;
@ApiModelProperty("年龄")
@ApiRequestInclude(groups = {SwaggerGroups.Insert.class})
private int age;
@ApiModelProperty("性别")
@ApiRequestInclude(groups = {SwaggerGroups.Insert.class})
private int sex;
@ApiModelProperty("真实姓名")
@ApiRequestInclude(groups = {SwaggerGroups.Insert.class})
private String realName;
@ApiModelProperty("地址")
@ApiRequestInclude(groups = {SwaggerGroups.Insert.class})
private String address;
}
控制层类上加入注解@ApiPlus(true)
@SpringBootApplication
@RestController
@Api(tags = "测试")
@ApiPlus(true)
public class SwaggerApplication {
方法上加入对应分组ApiGroup
@PostMapping("/insert")
@ApiGroup(groups = SwaggerGroups.Insert.class)
@ApiOperation(value = "新增用户", httpMethod = "POST")
public User insert(@RequestBody User user) {
user.setId(UUID.randomUUID().toString());
return user;
}
@GetMapping("/by-id/{id}")
@ApiOperation(value = "根据id查询用户", httpMethod = "GET")
public User insert(@PathVariable String id) {
User user = new User();
user.setUsername("test");
user.setPassword("123");
user.setAge(20);
return user;
}
@PostMapping("/login")
@ApiGroup(groups = SwaggerGroups.Login.class)
@ApiOperation(value = "登陆", httpMethod = "POST")
public User login(@RequestBody User user) {
user.setId(UUID.randomUUID().toString());
return user;
}
4. 最终效果
可以看到新增接口中id不见了, 登录也只剩下用户名和密码
新增
登录
以上是关于SpringBoot2整合Swagger2-plus的主要内容，如果未能解决你的问题，请参考以下文章
SpringBoot2.1.6 整合CXF 实现Webservice
SpringBoot2.1.6 整合CXF 实现Webservice