springboot整合swagger-最新ui界面

西门吹雪@132

已于 2023-11-17 13:32:15 修改

阅读量2.7k

点赞数

文章标签： spring boot java 后端 swagger

于 2023-06-15 10:13:49 首次发布

本文链接：https://blog.csdn.net/qq_50523945/article/details/131221916

版权

前言

千万注意一点，这个只能是测试环境使用，千万不要放到正式环境。这个一定要注意！！！

一、pom文件引入

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

swagger核心依赖（比较安全地址路径是不变的）

  <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.8</version>
        </dependency>

pom依赖：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <!--spring-boot 依赖版本-->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.3.12.RELEASE</version>
    </parent>
 
    <!--当前项目坐标-->
    <groupId>com.example</groupId>
    <artifactId>springboot-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot-demo</name>
    <description>springboot-demo</description>
 
    <!--版本依赖管理-->
    <properties>
        <java.version>8</java.version>
        <druid.version>1.2.15</druid.version>
        <mybatis-plus.version>3.4.2</mybatis-plus.version>
        <swagger.version>2.9.2</swagger.version>
    </properties>
 
 
    
    <dependencies>
        <!--spring-boot-starter 依赖-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
 
        <!--spring-boot-starter-web 依赖-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
 
        <!--热启动依赖-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
 
        <!--lombok 依赖-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
 
        <!--spring-boot-starter-test 依赖-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
 
        <!--mysql 链接驱动-->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
        </dependency>
 
        <!--druid数据库连接池-->
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid-spring-boot-starter</artifactId>
            <version>${druid.version}</version>
        </dependency>
 
        <!--mybatis-plus-->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
            <version>${mybatis-plus.version}</version>
        </dependency>
 
        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
 
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
 
        <!--swagger.ui-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.6</version>
        </dependency>
 
    </dependencies>
 
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
 
</project>

二、创建swagger配置类

首先把位置说明一下

package com.example.springbootdemo.config;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.builders.ApiInfoBuilder;
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
@Profile("dev")
public class SwaggerConfig {
    /**
     * 创建API应用 apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     */
    @Bean
    public Docket createRestApi() {
 
        return new Docket(DocumentationType.SWAGGER_2)
                //接口说明信息
                .apiInfo(apiInfo())
                // 选择那些路径和api会生成document
                .pathMapping("/").select()
                // 对所有api进行监控
                .apis(RequestHandlerSelectors.any())
                //.apis(RequestHandlerSelectors.basePackage("com.hty.tools.controller"))
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)).build();
    }
 
 
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试接口文档")
                .contact(new Contact("William","https://www.baidu.com","William940115@163.com"))
                .termsOfServiceUrl("https://www.baidu.com")
                .description("测试接口文档")
                .version("1.0")
                .build();
    }
 
}

说明：

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

三、创建测试类

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

package com.example.springbootdemo.controller;
 
import com.example.springbootdemo.entity.User;
import com.example.springbootdemo.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
 
/**
 * @description: TestController <br>
 * @date: 2022/12/17 0017 上午 10:06 <br>
 * @author: William <br>
 * @version: 1.0 <br>
 */
@Api(tags = "测试接口")
@RestController
@RequestMapping("test")
public class TestController {
 
    @Autowired
    private UserService userService;
 
 
    @ApiOperation("根据用户ID获取用户信息接口")
    @GetMapping("user/{id}")
    public String getUserById(@PathVariable("id") Integer id){
        //参数校验
        if(id == null || id<=0){
            return "参数非法";
        }
        User user = userService.getById(id);
        return user.toString();
    }
 
}

四、启动测试

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

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

五、swagger常用注解

swagger注解的使用可以自行百度或去官方文档看，很简单。

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

六、最终pom

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

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <!--spring-boot 依赖版本-->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.3.12.RELEASE</version>
    </parent>
 
    <!--当前项目坐标-->
    <groupId>com.example</groupId>
    <artifactId>springboot-demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot-demo</name>
    <description>springboot-demo</description>
 
    <!--版本依赖管理-->
    <properties>
        <java.version>8</java.version>
        <druid.version>1.2.15</druid.version>
        <mybatis-plus.version>3.4.2</mybatis-plus.version>
        <swagger.version>2.9.2</swagger.version>
        <swagger-ui.version>1.9.6</swagger-ui.version>
    </properties>
 
 
    <dependencies>
        <!--spring-boot-starter 依赖-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
 
        <!--spring-boot-starter-web 依赖-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
 
        <!--热启动依赖-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>
 
        <!--lombok 依赖-->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
 
        <!--spring-boot-starter-test 依赖-->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
 
        <!--mysql 链接驱动-->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
        </dependency>
 
        <!--druid数据库连接池-->
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid-spring-boot-starter</artifactId>
            <version>${druid.version}</version>
        </dependency>
 
        <!--mybatis-plus-->
        <dependency>
            <groupId>com.baomidou</groupId>
            <artifactId>mybatis-plus-boot-starter</artifactId>
            <version>${mybatis-plus.version}</version>
        </dependency>
 
        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
 
        <!--swagger.ui-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>${swagger-ui.version}</version>
        </dependency>
 
    </dependencies>
 
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
 
</project>