springboot整合swagger2

矫情吗；* 2022-09-08 10:27 308阅读 0赞

# 基础配置： #

## 一、 ##

##### pom.xml中引入swagger的依赖 #####

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.9.2</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.9.2</version>
            </dependency>

## 二、 ##

##### 创建最基本的swagger2配置 #####

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

## 三、 ##

##### 创建一个hello类 #####

@RestController
    @RequestMapping("main")
    public class HelloController { 
    
        @GetMapping("/hello")
        private String hello(){ 
            System.err.print("11111");
            return "hello world";
        }
    }

## 四、 ##

##### 测试，访问http://localhost:8088/swagger-ui.html即可 #####

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16]

# 进阶配置： #

## 一、 ##

##### 在config中修改API的信息 #####

package main.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    import java.util.ArrayList;
    
    @Configuration
    @EnableSwagger2 //开启swagger2
    public class SwaggerConfig { 
    
        //配置swagger的Docket的bean实例
        @Bean
        public Docket docket(){ 
            return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
        }
    
        private ApiInfo apiInfo(){ 
    
            //作者信息
            Contact contact = new Contact("刘建华","https://blog.csdn.net/weixin_45151960","3293829450@qq.com");
            return new ApiInfo(
                    "swagger2在线API文档",
                    "简介",
                    "v1.0",
                    "https://blog.csdn.net/weixin_45151960",
                    contact,
                    "license",
                    "licenseUrl",
                    new ArrayList<>());
        }
    }

效果如下：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 1]

## 配置扫描接口 ##

@Bean
       public Docket docket(){ 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    //basePackage("main.helloController") 指定要扫描的包
                    //any 扫描全部
                    //none 都不扫描
                    //withClassAnnotation(RequestMapping.class) 扫描类上的注解
                    //withMethodAnnotation(GetMapping.class) 扫描方法上面的注解 也可以说是扫描请求方式
                    .apis(RequestHandlerSelectors.basePackage("main.helloController"))
                    //paths 过滤什么路径
                    .paths(PathSelectors.ant(""))
                    .build();
        }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 2]

# 实战技能 #

## 在不同环境设置swagger ##

##### 如何在dev环境开启swagger，在test环境关闭swagger #####

一、  
在yml配置文件中先设置两种环境的配置

server:
      port: 8088
    
    spring:
      profiles: dev
    ---
    server:
      port: 8088
    
    spring:
      profiles: test
    
    ---
    spring:
      profiles:
        active: test

在swagger配置类中去获取当前环境

package main.config;
    
    import org.springframework.beans.factory.annotation.Value;
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.RequestMapping;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    import java.util.ArrayList;
    
    @Configuration
    @EnableSwagger2 //开启swagger2
    public class SwaggerConfig { 
    
        @Value("${spring.profiles.active}")
        private String string;
        //配置swagger的Docket的bean实例
    
        @Bean
        public Docket docket(){ 
            boolean b = false;
            //如果环境为dev开启 否则关闭
            if(string.equals("dev")){ 
                b = true;
            }
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    //enable 是否启动swagger 默认为true false时关闭swagger
                    .enable(b)
                    .select()
                    //basePackage("main.helloController") 指定要扫描的包
                    //any 扫描全部
                    //none 都不扫描
                    //withClassAnnotation(RequestMapping.class) 扫描类上的注解
                    //withMethodAnnotation(GetMapping.class) 扫描方法上面的注解 也可以说是扫描请求方式
                    .apis(RequestHandlerSelectors.basePackage("main.helloController"))
                    //paths 过滤什么路径
                    .paths(PathSelectors.ant(""))
                    .build();
        }
    
    
        private ApiInfo apiInfo(){ 
    
            //作者信息
            Contact contact = new Contact("刘建华","https://blog.csdn.net/weixin_45151960","3293829450@qq.com");
            return new ApiInfo(
                    "swagger2在线API文档",
                    "简介",
                    "v1.0",
                    "https://blog.csdn.net/weixin_45151960",
                    contact,
                    "license",
                    "licenseUrl",
                    new ArrayList<>());
        }
    }

情况1：  
选择test环境

spring:
      profiles:
        active: test

访问swagger如下：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 3]  
情况2：  
选择dev环境时

spring:
      profiles:
        active: dev

访问swagger如下：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 4]

# swagger配置多个分组 #

##### 创建多个docket实例即可，在实例中使用.groupName("")创建分组 #####

@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");
        }

效果如下：在每个分组中可以设置自己的信息  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 5]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 6]

# swagger常用注解 #

##### @ApiModel(“用户实体类”) 放类上面说明类信息 #####

##### @ApiModelProperty(“用户名”) 放字段上面说明字段信息 #####

##### @ApiOperation(“获取用户信息”)放接口上面说明接口信息 #####

##### @ApiParam(“用户id”)放请求参数前面说明参数信息 #####

package main.pojo;
    
    import io.swagger.annotations.ApiModel;
    import io.swagger.annotations.ApiModelProperty;
    
    @ApiModel("用户实体类")
    public class User { 
    
        @ApiModelProperty("用户名")
        public String name;
        @ApiModelProperty("密码")
        public String password;
    }

@ApiOperation("获取用户信息")
        @PostMapping("/user")
        private User user(){ 
            return new User();
        }
        
        @PostMapping("/test")
        private String test(@ApiParam("用户id") String id){ 
            return id;
        }

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 7]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 8]

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16]: /images/20220829/901e9a0d3a4c4c32bee3cf50af26e331.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 1]: /images/20220829/0da652aae616402585e31be09659ed3e.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 2]: /images/20220829/c6e1d6b33d7140be860e0384fdbac992.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 3]: /images/20220829/82deb04b6f784a8cbbf6ad42db432ab0.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 4]: /images/20220829/e99566030dd341179871cb5e4f3441bf.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 5]: /images/20220829/bd7f31ed72aa4d468ef06385b7e22c01.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 6]: /images/20220829/0dc77f45f8754c66be2c5bb818fe174a.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 7]: /images/20220829/66cf8ec32be347078b1a1c27990648cc.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_Q1NETiBA5ZOI5paX_size_67_color_FFFFFF_t_70_g_se_x_16 8]: /images/20220829/7f3011f193df43b0b53ccb348877eb8e.png