SpringBoot 整合Swagger2_springboot swagger2

一、Swagger简介

Swagger是一套开源工具和规范，用于设计、构建和文档化RESTful Web服务。它允许开发人员定义API的各个方面，并生成易于理解的API文档和交互式API探索界面。同时，Swagger还提供代码生成工具，可自动生成与API交互的客户端和服务器端代码，提高开发效率。

• 官网：https://swagger.io/

二、SpringBoot集成Swagger

使用Swagger

要求：jdk 1.8 + 否则swagger2无法运行

步骤：

1. 新建一个SpringBoot-web项目

2. 添加Maven依赖

   <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>
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11

3. 编写HelloController，测试确保运行成功！

   @RestController
   public class HelloController {
   
       @RequestMapping("/hello")
       public String hello(){
           return "hello swagger";
       }
   }
   1
   2
   3
   4
   5
   6
   7
   8

4. 要使用Swagger，我们需要编写一个配置类SwaggerConfig来配置 Swagger

    package com.liming.config;
    
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2// 开启Swagger2的自动配置
    public class SwaggerConfig extends WebMvcConfigurationSupport {
    
        /**
         * 解决高版本springboot无法访问http://localhost:8001/swagger-ui.html
         * @param registry void
         */
        @Override
        protected void addResourceHandlers(ResourceHandlerRegistry registry) {
            // 解决静态资源无法访问
            registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
            // 解决swagger无法访问
            registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
            // 解决swagger的js文件无法访问
            registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        }
    }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25

5. 访问测试 ：http://localhost:8080/swagger-ui.html ，可以看到swagger的界面；

   

三、配置Swagger

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

   @Bean //配置docket以配置Swagger具体参数
   public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2);
   }
   1
   2
   3
   4

2. 可以通过apiInfo()属性配置文档信息

    //配置文档信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger标题") // 标题
                .description("学习演示如何配置Swagger") //描述
                .version("v1.0") // 版本
                .contact(new Contact("黎明", "https://blog.csdn.net/weixin_46370595?type=blog", "2356731504@qq.com"))
                .build();
    }
   1
   2
   3
   4
   5
   6
   7
   8
   9

3. Docket 实例关联上 apiInfo()

   @Bean
   public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
   }
   1
   2
   3
   4

4. 重启项目，访问测试 http://localhost:8080/swagger-ui.html 看下效果；

   

四、配置扫描接口

1. 构建Docket时通过select()方法配置怎么扫描接口。

   @Bean
   public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
         .apis(RequestHandlerSelectors.basePackage("com.liming.controller"))
         .build();
   }
   1
   2
   3
   4
   5
   6
   7
   8

2. 重启项目测试，由于我们配置根据包的路径扫描接口，所以我们只能看到一个类

   

3. 除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：

   1、basePackage(final String basePackage) // 根据包路径扫描接口
   2、any() // 扫描所有，项目中的所有接口都会被扫描到
   3、none() // 不扫描接口

   4、// 通过方法上的注解扫描，如withMethodAnnotation(GetMapping.class)只扫描get请求
   withMethodAnnotation(final Class<? extends Annotation> annotation)
   5、// 通过类上的注解扫描，如.withClassAnnotation(Controller.class)只扫描有controller注解的类中的接口
   withClassAnnotation(final Class<? extends Annotation> annotation)

4. 除此之外，我们还可以配置接口扫描过滤：

   @Bean
   public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .select()
         .apis(RequestHandlerSelectors.basePackage("com.kuang.swagger.controller"))
          // 配置如何通过path过滤,即这里只扫描请求以/user开头的接口
         .paths(PathSelectors.ant("/user/**"))
         .build();
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10

5. 这里的可选值还有

   any() // 任何请求都扫描
   none() // 任何请求都不扫描
   regex(final String pathRegex) // 通过正则表达式控制
   ant(final String antPattern) // 通过ant()控制

SwaggerConfig基础配置全代码

package com.liming.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
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;


@Configuration
@EnableSwagger2// 开启Swagger2的自动配置
public class SwaggerConfig extends WebMvcConfigurationSupport {

    @Bean //配置docket以配置Swagger具体参数
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.limjing.controller")) // 只扫描controller接口
                .paths(PathSelectors.any()) // 配置如何通过path过滤,即这里扫描所有请求的接口
                .build();
    }

    //配置文档信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger标题") // 标题
                .description("学习演示如何配置Swagger") //描述
                .version("v1.0") // 版本
                .contact(new Contact("黎明", "https://blog.csdn.net/weixin_46370595?type=blog", "2356731504@qq.com"))
                .build();
    }

    /**
     * 解决高版本springboot无法访问http://localhost:8001/swagger-ui.html
     *
     * @param registry void
     */
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 解决静态资源无法访问
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        // 解决swagger无法访问
        registry.addResourceHandler("/swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        // 解决swagger的js文件无法访问
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

五、配置Swagger开关

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

   @Bean
   public Docket docket() {
      return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .enable(false) //配置是否启用Swagger，如果是false，在浏览器将无法访问
         .select()
         .apis(RequestHandlerSelectors.basePackage("nuc.ss.swagger.controller"))
         .paths(PathSelectors.ant("/ss/**"))
         .build();
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10

   

2. 如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？

   @Bean
   public Docket docket(Environment environment) {
      // 设置要显示swagger的环境
      Profiles of = Profiles.of("dev", "test");
      // 判断当前是否处于该环境
      // 通过 enable() 接收此参数判断是否要显示
      boolean flag = environment.acceptsProfiles(of);
      
      return new Docket(DocumentationType.SWAGGER_2)
         .apiInfo(apiInfo())
         .enable(flag)
         .select()
         .apis(RequestHandlerSelectors.basePackage("com.liming.controller"))
         .paths(PathSelectors.ant("/user/**"))
         .build();
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16

3. 可以在项目中增加配置文件

   application.yml ->spring.profiles.active=dev
   application-dev.yml ->端口：8081
   application-pro.yml->端口：8082

   结果：pro正式环境会关闭swagger功能

六、配置API分组

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

   @Bean
   public Docket docket(Environment environment) {
      return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
         .groupName("黎明") // 配置分组
          // 省略配置....
   }
   1
   2
   3
   4
   5
   6

2. 重启项目查看分组

   

3. 如何配置多个分组？配置多个分组只需要配置多个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");
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12

4. 重启项目查看即可

   

七、实体配置

1. 新建一个实体类

   //@Api("注释")
   @ApiModel("用户实体")
   public class User {
       @ApiModelProperty("用户名")
       private String username;
       @ApiModelProperty("密码")
       private String password;
   
       public String getUsername() {
           return username;
       }
   
       public void setUsername(String username) {
           this.username = username;
       }
   
       public String getPassword() {
           return password;
       }
   
       public void setPassword(String password) {
           this.password = password;
       }
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24

2. 只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

   @RestController
   public class HelloController {
   
       //   /error默认错误请求
       @GetMapping("/hello")
       public String hello() {
           return "hello";
       }
   
       //只要我们的接口中，返回值中存在实体类，他就会被扫描到Swagger中
       @PostMapping("/user")
       public User user() {
           return new User();
       }
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15

3. 重启查看测试

   

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的.

• @ApiModel为类添加注释

• @ApiModelProperty为类属性添加注释

【注意点】：在正式发布的时候，关闭Swagger！！！

常用注解

Swagger的所有注解定义在io.swagger.annotations包下

下面列一些经常用到的，未列举出来的可以另行查阅说明：

我们也可以给请求的接口配置一些注释

1. 在HelloController控制类中的接口添加api接口注释

   @RestController
   public class HelloController {
       ......
       @ApiOperation("Hello控制接口")
       @GetMapping("/hello")
       public String hello2(@ApiParam("用户名") String username) {
           return "hello" + username;
       }
       
       @ApiOperation("get测试")
       @GetMapping("/get")
       public User hello2(@ApiParam("用户") User user) {
           return user;
       }
       
    	@GetMapping("/users/{id}")
    	@ApiOperation(value = "获取用户详情")
    	@ApiImplicitParam(name = "id", value = "用户ID", paramType = "path", dataType = "Long", required = true)
    	public User getUserById(@PathVariable("id") Long id) {
    	    // 获取用户详情的业务逻辑
    	}
   
    	@GetMapping("/users")
    	@ApiOperation(value = "获取用户列表")
    	@ApiImplicitParams({
    	    @ApiImplicitParam(name = "page", value = "页码", paramType = "query", dataType = "int", defaultValue = "1"),
    	    @ApiImplicitParam(name = "size", value = "每页数量", paramType = "query", dataType = "int", defaultValue = "10")
    	})
    	public List<User> getUsers(@RequestParam(defaultValue = "1") int page, @RequestParam(defaultValue = "10") int size) {
    	    // 获取用户列表的业务逻辑
    	}
   }
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32

   

2. 进行try it out测试

   

   测试结果

   

拓展：其他皮肤

我们可以导入不同的包实现不同的皮肤定义：

1、默认的 访问 http://localhost:8080/swagger-ui.html

<dependency> 
   <groupId>io.springfox</groupId>
   <artifactId>springfox-swagger-ui</artifactId>
   <version>2.9.2</version>
</dependency>
1
2
3
4
5

2、bootstrap-ui 访问 http://localhost:8080/doc.html

<!--swaggerconfig解决高版本那里要换成doc.html-->
<!-- 引入swagger-bootstrap-ui包 /doc.html-->
<dependency>
   <groupId>com.github.xiaoymin</groupId>
   <artifactId>swagger-bootstrap-ui</artifactId>
   <version>1.9.1</version>
</dependency>
1
2
3
4
5
6
7

八.微服务使用Knife4j

官网地址:https://doc.xiaominfo.com/

第一步：创建Spring Boot项目并且在pom.xml中引入Knife4j的依赖包，代码如下：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>
1
2
3
4
5

第二步：配置yml属性，代码如下：

knife4j:
  enable: true #表示启用Knife4j，允许API文档生成和展示
  openapi: #表示配置OpenAPI相关的信息
    title: Knife4j官方文档 #设置了API文档的标题
    description: "`我是测试`,**你知道吗** #设置了API文档的描述
    email: 2356731504@qq.com #电子邮件地址
    concat: 黎明 #联系人的名称
    version: v1.0 
    license: Apache 2.0 #API使用的许可证为"Apache 2.0"
    license-url: https://stackoverflow.com/ #提供了许可证的URL链接
    terms-of-service-url: https://stackoverflow.com/ #提供了服务条款的URL链接
    group: #分组信息
      default:
        group-name: default #分组名称
        api-rule: package #按照包来进行API的分组
        api-rule-resources: #指定了API规则的资源信息
          - com.liming.controller
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

第三步:新建一个接口Controller类，如下：

@Api(tags = "首页模块")
@RestController
public class IndexController {

    @ApiImplicitParam(name = "name",value = "姓名",required = true)
    @ApiOperation(value = "向客人问好")
    @GetMapping("/sayHi")
    public ResponseEntity<String> sayHi(@RequestParam(value = "name")String name){
        return ResponseEntity.ok("Hi:"+name);
    }
}
1
2
3
4
5
6
7
8
9
10
11

万事俱备，启动Spring Boot项目，浏览器访问Knife4j的文档地址即可查看效果

http://ip:端口/doc.html