SpringBoot集成Swagger（详解配置Swagger信息、API文档分组以及介绍swagger常用注解的使用，附有文图+代码示例）

文章目录

Swagger详解

Swagger详解

1.1 SpringBoot集成Swagger

版本：

jdk 1.8
SpringBoot 2.6.13

创建Springboot项目

导入依赖

(建议下面三个依赖同时导入)

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

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

<!-- 3.0 版本直接导入这个也行-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>
       springfox-boot-starter
    </artifactId>
    <version>3.0.0</version>
</dependency>

在config包下创建SwaggerConfig配置类

@Configuration
// @EnableSwagger2 
//3.0版本后不用再加入@Enableopenapi @Enableswagger2这两个注解，
public class SwaggerConfig {
}

创建hello工程,编写HelloController，测试确保运行成功！

在这里插入图片描述

@RestController
public class HelloController {

    @RequestMapping("/hello")
    public String hello() {
        return "Hello World kwh....";
    }
}

启动项目输入http://localhost:8080/swagger-ui/index.html

（http://localhost:8080/swagger-ui.html,上面地址访问404就访问下面的地址）

(如果启动出错，在启动类或者配置类上加@EnableWebMvc注解)

在这里插入图片描述

1.2 配置Swagger

在config包下创建配置类SwaggerConfig

Swagger实例Bean是Docket，所以通过配置Docket实例来配置Swaggger。

通过apiInfo()属性配置文档信息

@Configuration
// @EnableSwagger2
public class SwaggerConfig {

    // 配置Swagger的Docket的bean实列
    //Docket 实例关联上 apiInfo()
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    // 配置swagger基本信息
    private ApiInfo apiInfo(){

        // 作者信息
        Contact contact = new Contact(
          "weiyi", 
          "https://blog.csdn.net/weixin_54555405", 
          "[email protected]");

        return new ApiInfo(
                "weiyi的swagger",
                "追风赶月莫停留",
                "1.0",
                "https://blog.csdn.net/weixin_54555405",
                contact,
               "Apache 2.0",
               "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }
}

重新启动项目输入http://localhost:8080/swagger-ui/index.html

在这里插入图片描述

1.3 swagger配置扫描接口

通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口

groupName(“kwh”)//分组名称

apis：

RequestHandlerSelectors扫描接口的方式
basePackage指定扫描包
any（）扫描全部
none（）不扫描

withclassannotation 扫描类的注解（里面必须放注解的反射对象）

apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)

通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口

withmethodAnnotation 扫描方法上的注解

apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class)


通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求

path：过滤路径不被扫描到

paths(PathSelectors.ant(“/user/*”))

配置如何通过path过滤,即这里只扫描请求以/user开头的接口

通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了

@Configuration
// @EnableSwagger2
public class SwaggerConfig {
  
     /**
         *  Swagger实例Bean是Docket，
         *  所以通过配置Docket实例来配置Swaggger。
         */

    // 配置Swagger的Docket的bean实列
    //Docket 实例关联上 apiInfo()
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("kwh")//分组名称
                .enable(true)//开启swagger
                .select()
                .apis(RequestHandlerSelectors
          .basePackage("com.ithz.controller"))
          // 配置如何通过path过滤,即这里只扫描请求以/user开头的接口
                .paths(PathSelectors.ant("/user/*"))
                .build();
    }

    // 配置swagger基本信息
    private ApiInfo apiInfo(){

       // 作者信息
        Contact contact = new Contact(
                "weiyi",  //联系人
                //联系人博客
                "https://blog.csdn.net/weixin_54555405",  
                "[email protected]"); //联系人邮箱

      //以下配置信息会在首页中显示
        return new ApiInfo(
                "weiyi的swagger",//标题
                "追风赶月莫停留",  //描述
                "1.0",  //版本
          
                //组织链接
                "https://blog.csdn.net/weixin_54555405",
                contact,  //联系人信息
                "Apache 2.0",  //许可
          
               //许可链接
               "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());  //扩展
    }

}

在这里插入图片描述

1.4 动态配置不同环境下的Swagger有效

首先创建多个配置文件，

application-dev.properties,application-test.properties

在这里插入图片描述

让swagger在开发环境中生效

在这里插入图片描述

修改SwaggerConfig配置类

增加如下代码

在这里插入图片描述

修改后的SwaggerConfig配置类（完整）：

@Configuration
// @EnableSwagger2
public class SwaggerConfig {

    @Autowired
    private Environment environment;

    // 配置Swagger的Docket的bean实列
    @Bean
    public Docket docket(){

        //设置要显示的swagger环境，如当前是开发环境显示swagger
        Profiles profiles = Profiles.of("dev");
        //判断是否处在自己设置的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        System.out.println(flag);

        /**
         *  Swagger实例Bean是Docket，
         *  所以通过配置Docket实例来配置Swaggger。
         */

        // 可以通过apiInfo()属性配置文档信息
        //Docket 实例关联上 apiInfo()
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)//开启swagger
                .select()
                .apis(
          RequestHandlerSelectors
          .basePackage("com.ithz.controller"))//扫描指定包
                .build();
    }

    // 配置swagger基本信息
    private ApiInfo apiInfo(){

        // 作者信息
        Contact contact = new Contact(
                "weiyi",  //联系人
          
                //联系人博客
                "https://blog.csdn.net/weixin_54555405",  
                "[email protected]"); //联系人邮箱

        return new ApiInfo(
                "weiyi的swagger",//标题
                "追风赶月莫停留",//描述
                "1.0",//版本
          
                //组织链接
                "https://blog.csdn.net/weixin_54555405",
                contact,  //联系人信息
                "Apache 2.0",//许可
                //许可链接
               "http://www.apache.org/licenses/LICENSE-2.0",  
                new ArrayList());//扩展
    }


}

当前是让开发环境（端口号8081）生效，访问http://localhost:8081/swagger-ui/index.html

访问8080,则失效

在这里插入图片描述

1.5 配置API文档分组

如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

@Bean
public Docket docket(Environment environment) {
   return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
      .groupName("hello") // 配置分组
       // 省略配置....
}

如何配置多个分组？配置多个分组只需要配置多个docket即可：

@Bean
public Docket docket1(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group1");
}
@Bean
public Docket docket2(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group2");
}
@Bean
public Docket docket3(){
   return new Docket(DocumentationType.SWAGGER_2).groupName("group3");
}

完整配置类代码：

@Configuration
// @EnableSwagger2
public class SwaggerConfig {

    @Autowired
    private Environment environment;

    // 配置Swagger的Docket的bean实列
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2)
          .groupName("group1");
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2)
          .groupName("group2");
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2)
          .groupName("group3");
    }
    @Bean
    public Docket docket(){

        //设置要显示的swagger环境，如当前是开发环境显示swagger
        Profiles profiles = Profiles.of("dev");
        //判断是否处在自己设置的环境中
        boolean flag = environment.acceptsProfiles(profiles);
        System.out.println(flag);

        /**
         *  Swagger实例Bean是Docket，
         *  所以通过配置Docket实例来配置Swaggger。
         */

        // 可以通过apiInfo()属性配置文档信息
        //Docket 实例关联上 apiInfo()
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)//开启swagger
                .select()
                .apis(RequestHandlerSelectors
                      .basePackage("com.ithz.controller"))
               
                .build();
    }

    // 配置swagger基本信息
    private ApiInfo apiInfo(){

        // 作者信息
        Contact contact = new Contact(
                "weiyi",  //联系人
                "https://blog.csdn.net/weixin_54555405",  
                "[email protected]"); //联系人邮箱

        return new ApiInfo(
                "weiyi的swagger",//标题
                "追风赶月莫停留",//描述
                "1.0",//版本
                "https://blog.csdn.net/weixin_54555405",
                contact,  //联系人信息
                "Apache 2.0",//许可
               "http://www.apache.org/licenses/LICENSE-2.0", 
                new ArrayList());//扩展
    }


}

在这里插入图片描述

1.6 实体配置

简单实体配置

在pojo包下创建实体类User

@Data
public class User {

    private String username;
    private String password;
}

controller层

@RestController
public class HelloController {

    @RequestMapping("/hello")
    public String hello() {
        return "Hello World";
    }

    //只要接口中返回值存在实体类，就会被扫描到Swagger中
    @PostMapping("/user")
    public User user() {
        return new User();
    }
}

SwaggerConfig配置类同1.5中的一样

输入测试地址http://localhost:8081/swagger-ui/index.html

(默认分组、group1、grou2、group3中都有实体类信息)

在这里插入图片描述

常用注解

Swagger注解	简单说明
@Api(tags = “xxx模块说明”)	作用在模块类上
@ApiOperation(“xxx接口说明”)	作用在接口方法上
@ApiModel(“xxxPOJO说明”)	作用在模型类上：如VO、BO
@ApiModelProperty(value = “xxx属性说明”,hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam(“xxx参数说明”)	作用在参数、方法和字段上，类似@ApiModelProperty

实体类上加Swagger注解

@Data
@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("用户密码")
    private String password;

}

在这里插入图片描述

controller类中加Swagger注解

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello World";
    }

    //只要接口中返回值存在实体类，就会被扫描到Swagger中
    @PostMapping("/user")
    public User user() {
        return new User();
    }

    @ApiOperation(value = "hello02接口")
    @GetMapping("/hello02")
    public String hello02(@ApiParam("用户名") String name) {
        return "Hello World"+name;
    }
}

在这里插入图片描述