SpringBoot2整合Swagger2-plus

时间：2020-11-16 12:58:29 阅读：17 评论：0 收藏：0 [点我收藏+]

标签：toc prope 姓名一个 class 产生 image variable login

一.整合swagger2
二. 整合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. 实际效果

查询

技术图片

新增

技术图片

二. 整合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不见了, 登录也只剩下用户名和密码

新增

技术图片