springboot整合swagger

特别说明：本次项目整合基于idea进行的，如果使用Eclipse可能操作会略有不同，不过总的来说不影响。

springboot整合之如何选择版本及项目搭建

springboot整合之版本号统一管理 

springboot整合mybatis-plus durid数据库连接池

springboot整合swagger

springboot整合mybatis代码快速生成

springboot整合之统一结果返回

springboot整合之统一异常处理

springboot整合之Validated参数校验

springboot整合之logback日志配置

springboot整合pagehelper分页

springboot整合本地缓存

springboot整合redis redisson

springboot整合elasticsearch

springboot整合rabbitMq

springboot整合canal实现缓存一致性

springboot整合springSecurity(前后端不分离版本)

在开始之前先说一下自己的理解。我觉得既然要使用，首先就要知道为什么要用？该不该用？如果说我们的项目就俩人开发的一个小项目，又没有前后端分离，而且有比较急着上线，那我觉得这种真是没有必要用swagger。这里只是举个例子，就是告诉大家没有必要为了swagger而swagger。

我认为swagger更适合前后端分离情况，或者需要协同开发给别人提供接口测试的时候使用。在这种情况下能够提高协同的效率。如果一项技术的引进不能提高开发效率，或者对项目本身没有什么提升，我觉得引入的意义就不大。而且引入很多没用的文件对内存也是影响，有时候甚至会影响我们程序的性能。

如果确定适合，那就整合进来。但是千万注意一点。这个只能是测试环境使用，千万不要放到正式环境。这个一定要注意！！！关于怎么设置正式环境不可用会在本次整合中给出示范。

我在项目开发中用过两种不同风格的swagger UI，这里会都展示一下，具体用那种大家可以根据需要来选择就好了。

一、pom文件引入

因为跟之前的几次的整合相比这次对版本进行了统一的依赖管理，所以直接贴上了所有的整合pom,如果有小伙伴是按照之前一步一步来的，这里直接替换pom就好了。

1.  
   <?xml version="1.0" encoding="UTF-8"?>
2.  
   <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3.  
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
4.  
   <modelVersion>4.0.0</modelVersion>
5.  
   <!--spring-boot 依赖版本-->
6.  
   <parent>
7.  
   <groupId>org.springframework.boot</groupId>
8.  
   <artifactId>spring-boot-starter-parent</artifactId>
9.  
   <version>2.3.12.RELEASE</version>
10.  
    </parent>
11.  
     
12.  
    <!--当前项目坐标-->
13.  
    <groupId>com.example</groupId>
14.  
    <artifactId>springboot-demo</artifactId>
15.  
    <version>0.0.1-SNAPSHOT</version>
16.  
    <name>springboot-demo</name>
17.  
    <description>springboot-demo</description>
18.  
     
19.  
    <!--版本依赖管理-->
20.  
    <properties>
21.  
    <java.version>8</java.version>
22.  
    <druid.version>1.2.15</druid.version>
23.  
    <mybatis-plus.version>3.4.2</mybatis-plus.version>
24.  
    <swagger.version>2.9.2</swagger.version>
25.  
    </properties>
26.  
     
27.  
     
28.  
     
29.  
    <dependencies>
30.  
    <!--spring-boot-starter 依赖-->
31.  
    <dependency>
32.  
    <groupId>org.springframework.boot</groupId>
33.  
    <artifactId>spring-boot-starter</artifactId>
34.  
    </dependency>
35.  
     
36.  
    <!--spring-boot-starter-web 依赖-->
37.  
    <dependency>
38.  
    <groupId>org.springframework.boot</groupId>
39.  
    <artifactId>spring-boot-starter-web</artifactId>
40.  
    </dependency>
41.  
     
42.  
    <!--热启动依赖-->
43.  
    <dependency>
44.  
    <groupId>org.springframework.boot</groupId>
45.  
    <artifactId>spring-boot-devtools</artifactId>
46.  
    <scope>runtime</scope>
47.  
    <optional>true</optional>
48.  
    </dependency>
49.  
     
50.  
    <!--lombok 依赖-->
51.  
    <dependency>
52.  
    <groupId>org.projectlombok</groupId>
53.  
    <artifactId>lombok</artifactId>
54.  
    <optional>true</optional>
55.  
    </dependency>
56.  
     
57.  
    <!--spring-boot-starter-test 依赖-->
58.  
    <dependency>
59.  
    <groupId>org.springframework.boot</groupId>
60.  
    <artifactId>spring-boot-starter-test</artifactId>
61.  
    <scope>test</scope>
62.  
    </dependency>
63.  
     
64.  
    <!--mysql 链接驱动-->
65.  
    <dependency>
66.  
    <groupId>mysql</groupId>
67.  
    <artifactId>mysql-connector-java</artifactId>
68.  
    </dependency>
69.  
     
70.  
    <!--druid数据库连接池-->
71.  
    <dependency>
72.  
    <groupId>com.alibaba</groupId>
73.  
    <artifactId>druid-spring-boot-starter</artifactId>
74.  
    <version>${druid.version}</version>
75.  
    </dependency>
76.  
     
77.  
    <!--mybatis-plus-->
78.  
    <dependency>
79.  
    <groupId>com.baomidou</groupId>
80.  
    <artifactId>mybatis-plus-boot-starter</artifactId>
81.  
    <version>${mybatis-plus.version}</version>
82.  
    </dependency>
83.  
     
84.  
    <!--swagger-->
85.  
    <dependency>
86.  
    <groupId>io.springfox</groupId>
87.  
    <artifactId>springfox-swagger2</artifactId>
88.  
    <version>${swagger.version}</version>
89.  
    </dependency>
90.  
     
91.  
    <dependency>
92.  
    <groupId>io.springfox</groupId>
93.  
    <artifactId>springfox-swagger-ui</artifactId>
94.  
    <version>${swagger.version}</version>
95.  
    </dependency>
96.  
     
97.  
    <!--swagger.ui-->
98.  
    <dependency>
99.  
    <groupId>com.github.xiaoymin</groupId>
100.  
     <artifactId>swagger-bootstrap-ui</artifactId>
101.  
     <version>1.9.6</version>
102.  
     </dependency>
103.  
      
104.  
     </dependencies>
105.  
      
106.  
     <build>
107.  
     <plugins>
108.  
     <plugin>
109.  
     <groupId>org.springframework.boot</groupId>
110.  
     <artifactId>spring-boot-maven-plugin</artifactId>
111.  
     <configuration>
112.  
     <excludes>
113.  
     <exclude>
114.  
     <groupId>org.projectlombok</groupId>
115.  
     <artifactId>lombok</artifactId>
116.  
     </exclude>
117.  
     </excludes>
118.  
     </configuration>
119.  
     </plugin>
120.  
     </plugins>
121.  
     </build>
122.  
      
123.  
     </project>

二、创建swagger配置类

首先把位置说明一下

1.  
   package com.example.springbootdemo.config;
2.  
    
3.  
   import org.springframework.context.annotation.Bean;
4.  
   import org.springframework.context.annotation.Configuration;
5.  
   import org.springframework.context.annotation.Profile;
6.  
   import org.springframework.web.bind.annotation.RestController;
7.  
   import springfox.documentation.builders.ApiInfoBuilder;
8.  
   import springfox.documentation.builders.RequestHandlerSelectors;
9.  
   import springfox.documentation.service.ApiInfo;
10.  
    import springfox.documentation.service.Contact;
11.  
    import springfox.documentation.spi.DocumentationType;
12.  
    import springfox.documentation.spring.web.plugins.Docket;
13.  
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
14.  
     
15.  
    @Configuration
16.  
    @EnableSwagger2
17.  
    @Profile("dev")
18.  
    public class SwaggerConfig {
19.  
    /**
20.  
    * 创建API应用 apiInfo() 增加API相关信息
21.  
    * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
22.  
    * 本例采用指定扫描的包路径来定义指定要建立API的目录。
23.  
    */
24.  
    @Bean
25.  
    public Docket createRestApi() {
26.  
     
27.  
    return new Docket(DocumentationType.SWAGGER_2)
28.  
    //接口说明信息
29.  
    .apiInfo(apiInfo())
30.  
    // 选择那些路径和api会生成document
31.  
    .pathMapping("/").select()
32.  
    // 对所有api进行监控
33.  
    .apis(RequestHandlerSelectors.any())
34.  
    .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)).build();
35.  
    }
36.  
     
37.  
     
38.  
    /**
39.  
    * 创建该API的基本信息（这些基本信息会展现在文档页面中）
40.  
    *
41.  
    * @return
42.  
    */
43.  
    private ApiInfo apiInfo() {
44.  
    return new ApiInfoBuilder()
45.  
    .title("测试接口文档")
46.  
    .contact(new Contact("William","https://www.百度.com","William940115@163.com"))
47.  
    .termsOfServiceUrl("https://www.百度.com")
48.  
    .description("测试接口文档")
49.  
    .version("1.0")
50.  
    .build();
51.  
    }
52.  
     
53.  
    }

说明：

@Configuration   将当前配置类交给spring管理
@EnableSwagger2  开启swagger注解，此注解也可以添加到spring boot启动类
@Profile("dev")  开启只有dev环境生效，此外swagger也提供了基于环境的可见性设置，这里就不作详细介绍了，如果感兴趣的可以自己研究一下，也很简单。

三、创建测试类

 因为测试，我们先临时写一个测试类，主要就是测试我们的swagger是否整合成功。

1.  
   package com.example.springbootdemo.controller;
2.  
    
3.  
   import com.example.springbootdemo.entity.User;
4.  
   import com.example.springbootdemo.service.UserService;
5.  
   import io.swagger.annotations.Api;
6.  
   import io.swagger.annotations.ApiOperation;
7.  
   import org.springframework.beans.factory.annotation.Autowired;
8.  
   import org.springframework.web.bind.annotation.GetMapping;
9.  
   import org.springframework.web.bind.annotation.PathVariable;
10.  
    import org.springframework.web.bind.annotation.RequestMapping;
11.  
    import org.springframework.web.bind.annotation.RestController;
12.  
     
13.  
    /**
14.  
    * @description: TestController <br>
15.  
    * @date: 2022/12/17 0017 上午 10:06 <br>
16.  
    * @author: William <br>
17.  
    * @version: 1.0 <br>
18.  
    */
19.  
    @Api(tags = "测试接口")
20.  
    @RestController
21.  
    @RequestMapping("test")
22.  
    public class TestController {
23.  
     
24.  
    @Autowired
25.  
    private UserService userService;
26.  
     
27.  
     
28.  
    @ApiOperation("根据用户ID获取用户信息接口")
29.  
    @GetMapping("user/{id}")
30.  
    public String getUserById(@PathVariable("id") Integer id){
31.  
    //参数校验
32.  
    if(id == null || id<=0){
33.  
    return "参数非法";
34.  
    }
35.  
    User user = userService.getById(id);
36.  
    return user.toString();
37.  
    }
38.  
     
39.  
    }

四、启动测试

首先给大家看一下我比较喜欢的一种，输入http://localhost:8080/doc.html进行访问

 各人觉得很不错的一个UI页面，看起来很舒服。而且支持离线导出，相当给力。个人觉得比swagger自带的UI要好用一点。

然后就是另一种：输入http://localhost:8080/swagger-ui.html

 这种是我们比较常见的。我以前也经常用，后来发现了第一种这种就没用了。

 OK，到这里整合就完成了。下面就是常用的一些注解了。

五、swagger常用注解 

从官方给的解释，各位学习使用的时候建议直接从这里看，而且都给了例子，很简单。

好了，到这里我们swagger就整合好了。另外说一下，为了展示两种效果所以我在pom中引入了两个swagger-ui的jar包，后面我会删掉一个，只保留一个。大家可以根据自己需要来。我觉得最好只保留一个就好了。

六、最终pom

我保留的是我比较喜欢的一个，修改以后的pom文件如下：如果跟我一样的可以直接复制到自己的项目。

1.  
   <?xml version="1.0" encoding="UTF-8"?>
2.  
   <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3.  
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
4.  
   <modelVersion>4.0.0</modelVersion>
5.  
   <!--spring-boot 依赖版本-->
6.  
   <parent>
7.  
   <groupId>org.springframework.boot</groupId>
8.  
   <artifactId>spring-boot-starter-parent</artifactId>
9.  
   <version>2.3.12.RELEASE</version>
10.  
    </parent>
11.  
     
12.  
    <!--当前项目坐标-->
13.  
    <groupId>com.example</groupId>
14.  
    <artifactId>springboot-demo</artifactId>
15.  
    <version>0.0.1-SNAPSHOT</version>
16.  
    <name>springboot-demo</name>
17.  
    <description>springboot-demo</description>
18.  
     
19.  
    <!--版本依赖管理-->
20.  
    <properties>
21.  
    <java.version>8</java.version>
22.  
    <druid.version>1.2.15</druid.version>
23.  
    <mybatis-plus.version>3.4.2</mybatis-plus.version>
24.  
    <swagger.version>2.9.2</swagger.version>
25.  
    <swagger-ui.version>1.9.6</swagger-ui.version>
26.  
    </properties>
27.  
     
28.  
     
29.  
     
30.  
    <dependencies>
31.  
    <!--spring-boot-starter 依赖-->
32.  
    <dependency>
33.  
    <groupId>org.springframework.boot</groupId>
34.  
    <artifactId>spring-boot-starter</artifactId>
35.  
    </dependency>
36.  
     
37.  
    <!--spring-boot-starter-web 依赖-->
38.  
    <dependency>
39.  
    <groupId>org.springframework.boot</groupId>
40.  
    <artifactId>spring-boot-starter-web</artifactId>
41.  
    </dependency>
42.  
     
43.  
    <!--热启动依赖-->
44.  
    <dependency>
45.  
    <groupId>org.springframework.boot</groupId>
46.  
    <artifactId>spring-boot-devtools</artifactId>
47.  
    <scope>runtime</scope>
48.  
    <optional>true</optional>
49.  
    </dependency>
50.  
     
51.  
    <!--lombok 依赖-->
52.  
    <dependency>
53.  
    <groupId>org.projectlombok</groupId>
54.  
    <artifactId>lombok</artifactId>
55.  
    <optional>true</optional>
56.  
    </dependency>
57.  
     
58.  
    <!--spring-boot-starter-test 依赖-->
59.  
    <dependency>
60.  
    <groupId>org.springframework.boot</groupId>
61.  
    <artifactId>spring-boot-starter-test</artifactId>
62.  
    <scope>test</scope>
63.  
    </dependency>
64.  
     
65.  
    <!--mysql 链接驱动-->
66.  
    <dependency>
67.  
    <groupId>mysql</groupId>
68.  
    <artifactId>mysql-connector-java</artifactId>
69.  
    </dependency>
70.  
     
71.  
    <!--druid数据库连接池-->
72.  
    <dependency>
73.  
    <groupId>com.alibaba</groupId>
74.  
    <artifactId>druid-spring-boot-starter</artifactId>
75.  
    <version>${druid.version}</version>
76.  
    </dependency>
77.  
     
78.  
    <!--mybatis-plus-->
79.  
    <dependency>
80.  
    <groupId>com.baomidou</groupId>
81.  
    <artifactId>mybatis-plus-boot-starter</artifactId>
82.  
    <version>${mybatis-plus.version}</version>
83.  
    </dependency>
84.  
     
85.  
    <!--swagger-->
86.  
    <dependency>
87.  
    <groupId>io.springfox</groupId>
88.  
    <artifactId>springfox-swagger2</artifactId>
89.  
    <version>${swagger.version}</version>
90.  
    </dependency>
91.  
     
92.  
    <!--swagger.ui-->
93.  
    <dependency>
94.  
    <groupId>com.github.xiaoymin</groupId>
95.  
    <artifactId>swagger-bootstrap-ui</artifactId>
96.  
    <version>${swagger-ui.version}</version>
97.  
    </dependency>
98.  
     
99.  
    </dependencies>
100.  
      
101.  
     <build>
102.  
     <plugins>
103.  
     <plugin>
104.  
     <groupId>org.springframework.boot</groupId>
105.  
     <artifactId>spring-boot-maven-plugin</artifactId>
106.  
     <configuration>
107.  
     <excludes>
108.  
     <exclude>
109.  
     <groupId>org.projectlombok</groupId>
110.  
     <artifactId>lombok</artifactId>
111.  
     </exclude>
112.  
     </excludes>
113.  
     </configuration>
114.  
     </plugin>
115.  
     </plugins>
116.  
     </build>
117.  
      
118.  
     </project>

如果文章对你有所帮助的话，可以点赞关注一下~

这篇好文章是转载于：学新通技术网