【Springboot】整合Swagger（配置swagger信息、分组、接口扫描、实体类、控制器备注）

╰+攻爆jí腚メ 2022-09-17 01:52 63阅读 0赞

### 文章目录 ###

*  一、基本配置
 *   *  1.1 依赖
     *  1.2 配置类
     *  1.3 启动
 *  二、配置
 *   *  2.1 配置Swagger信息
     *  2.2 配置接口信息
     *  2.3 配置API文档分组
     *  2.4 实体类、控制器备注

# 一、基本配置 #

## 1.1 依赖 ##

找一个之前的Springboot项目，为其添加依赖。

链接：[https://mvnrepository.com/search?q=springfox+swagger][https_mvnrepository.com_search_q_springfox_swagger]

<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>

## 1.2 配置类 ##

启动Swagger2

import org.springframework.context.annotation.Configuration;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2
    public class SwaggerConfig { 
    }

## 1.3 启动 ##

启动项目后，打开浏览器：[http://localhost:8080/swagger-ui.html][http_localhost_8080_swagger-ui.html]

可查看到如下界面  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5pyb5aSp6L655pif5a6_size_20_color_FFFFFF_t_70_g_se_x_16]

1.  Swagger信息
2.  接口信息
3.  实体类信息
4.  组

# 二、配置 #

## 2.1 配置Swagger信息 ##

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
    public class SwaggerConfig { 
        // 配置Swagger的Docket实例
        @Bean
        public Docket docket() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo());
        }
    
        // 配置Swagger信息——ApiInfo
        private ApiInfo apiInfo() { 
            // 作者信息
            Contact contact = new Contact("小明","url","xiaoming@qq.com");
            return new ApiInfo(
                    "小明的Swagger",
                    "这里是描述文档",
                    "1.0",
                    "urn:tos",
                    contact,
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LICENSE-2.0",
                    new ArrayList());
        }
    }

## 2.2 配置接口信息 ##

接着上面的配置，继续修改。

import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    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
    public class SwaggerConfig { 
        // 配置Swagger的Docket实例
        @Bean
        public Docket docket() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .enable(true)   // false 关闭swagger; true 启动swagger
                    .select()
                    // RequestHandlerSelectors 配置要扫描接口的方式
                    // basePackage() 指定要扫描的包
                    // any() 扫描全部
                    // none() 不扫描
                    // withClassAnnotation() 扫描类上的注解 .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                    // withMethodAnnotation() 扫描方法上的注解 .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                    .apis(RequestHandlerSelectors.basePackage("com.zqc.personmanagement.Controller"))
                    .paths(PathSelectors.ant("/Controller"))  // 过滤路径
                    .build();
        }
    
        // 配置Swagger信息——ApiInfo
        private ApiInfo apiInfo() { 
            // 作者信息
            Contact contact = new Contact("小明","url","xiaoming@qq.com");
            return new ApiInfo(
                    "小明的Swagger",
                    "这里是描述文档",
                    "1.0",
                    "urn:tos",
                    contact,
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LICENSE-2.0",
                    new ArrayList());
        }
    }

## 2.3 配置API文档分组 ##

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

代码如下：

import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    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
    public class SwaggerConfig { 
        // 配置Swagger的Docket实例
        @Bean
        public Docket docket() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .groupName("新分组")
                    .enable(true)   // false 关闭swagger; true 启动swagger
                    .select()
                    // RequestHandlerSelectors 配置要扫描接口的方式
                    // basePackage() 指定要扫描的包
                    // any() 扫描全部
                    // none() 不扫描
                    // withClassAnnotation() 扫描类上的注解 .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                    // withMethodAnnotation() 扫描方法上的注解 .apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                    .apis(RequestHandlerSelectors.basePackage("com.zqc.personmanagement.Controller"))
                    .paths(PathSelectors.ant("/Controller"))  // 过滤路径
                    .build();
        }
    
        // 配置Swagger信息——ApiInfo
        private ApiInfo apiInfo() { 
            // 作者信息
            Contact contact = new Contact("小明","url","xiaoming@qq.com");
            return new ApiInfo(
                    "小明的Swagger",
                    "这里是描述文档",
                    "1.0",
                    "urn:tos",
                    contact,
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LICENSE-2.0",
                    new ArrayList());
        }
    
        @Bean
        public Docket docket1() { 
            return new Docket(DocumentationType.SWAGGER_2).groupName("A");
        }
    
        @Bean
        public Docket docket2() { 
            return new Docket(DocumentationType.SWAGGER_2).groupName("B");
        }
    }

后面再配置docket1和docket2就可以有多个分组了。  
![在这里插入图片描述][d4f3292ccd294b6ba93584a70a1d34ba.png]

## 2.4 实体类、控制器备注 ##

创建一个实体类 ，如下：

`src/main/java/com/zqc/personmanagement/pojo/User.java`

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

添加一个控制器，如下：  
`src/main/java/com/zqc/personmanagement/Controller/SwaggerController.java`

import com.zqc.personmanagement.pojo.User;
    import io.swagger.annotations.ApiOperation;
    import io.swagger.annotations.ApiParam;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RestController;
    
    @RestController
    public class SwaggerController { 
    
        @ApiOperation("User的控制类")
        // 只要接口中，返回值中存在实体类，就会被扫描到Swagger内
        @PostMapping(value = "/user")
        public User user(@ApiParam("用户名") String name) { 
            return new User();
        }
    }

此时运行Swagger-UI可查看到其中的模型：  
![在这里插入图片描述][228ef55ee6ae4d07891ec41263c22861.png]  
![在这里插入图片描述][watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5pyb5aSp6L655pif5a6_size_20_color_FFFFFF_t_70_g_se_x_16 1]

`@ApiModel("用户实体类")`：作用于类的注释，将显示的类名转换为备注。

`@ApiModelProperty("用户名")`：作用域属性，为属性添加备注。

`@ApiOperation("User的控制类")`：为控制器添加备注。

`@ApiParam("用户名")`：为方法中的属性添加备注。

参考：[https://www.bilibili.com/video/BV1PE411i7CV?p=50][https_www.bilibili.com_video_BV1PE411i7CV_p_50]

[https_mvnrepository.com_search_q_springfox_swagger]: https://mvnrepository.com/search?q=springfox%20swagger
[http_localhost_8080_swagger-ui.html]: http://localhost:8080/swagger-ui.html
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5pyb5aSp6L655pif5a6_size_20_color_FFFFFF_t_70_g_se_x_16]: /images/20220828/eb02bfad3b564f2599a6650067d0274f.png
[d4f3292ccd294b6ba93584a70a1d34ba.png]: /images/20220828/57e6ea57df1947128b7c93443e34566a.png
[228ef55ee6ae4d07891ec41263c22861.png]: /images/20220828/e90cca4377b14c9e8f515ed964089213.png
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBA5pyb5aSp6L655pif5a6_size_20_color_FFFFFF_t_70_g_se_x_16 1]: /images/20220828/3fb341ffe5fc41a8834cc99ddde3badd.png
[https_www.bilibili.com_video_BV1PE411i7CV_p_50]: https://www.bilibili.com/video/BV1PE411i7CV?p=50