SpringBoot整合Swagger3，赶紧整起来！

---

一、Swagger是什么？

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法、参数和模型紧密集成到服务器端的代码，允许 API 来始终保持同步。Swagger 让部署管理和使用功能强大的 API 从未如此简单。

二、使用步骤

1.引入swagger3依赖

代码如下：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2.添加swagger.conf配置类

代码如下：

package com.uhu.swagger;


import io.swagger.models.auth.In;
import liquibase.repackaged.org.apache.commons.lang3.reflect.FieldUtils;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.servlet.config.annotation.InterceptorRegistration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.lang.reflect.Field;
import java.util.Arrays;
import java.util.Collections;
import java.util.HashSet;
import java.util.List;
import org.springframework.context.annotation.Configuration;

/**
 * @author liujunjie
 * @description swagger配置
 * @create 2023-11-06 15:16
 **/
@Configuration 
// 声明开启swagger2
@EnableOpenApi
public class SwaggerConfig implements WebMvcConfigurer {

    /**
     * 是否开启swagger
     */
    @Value("${uhu.swagger.enable}")
    private Boolean enable;

    /**
     * 标题
     */
    @Value("${uhu.swagger.title}")
    private String title;

    /**
     * 版本
     */
    @Value("${uhu.swagger.version}")
    private String version;

    /**
     * 描述
     */
    @Value("${uhu.swagger.description}")
    private String description;

    /**
     * 扫描的包
     */

    @Value("${uhu.swagger.scanPackage}")
    private String scanPackage;

    /**
     * 接口调试地址
     */
    @Value("${uhu.swagger.host}")
    private String host;

    @Bean
    Docket api() {
        // springfox 的基本API配置
        return new Docket(DocumentationType.OAS_30)
                // 将映射的路径当作base Path，添加给apis
                .pathMapping("/")
                // 定义是否开启swagger，false为关闭，可以通过变量控制
                .enable(enable)

                // 将api的元信息设置为包含在json ResourceListing响应中。
                .apiInfo(apiInfo())

                // 接口调试地址
                .host(host)

                // 选择哪些接口作为swagger的doc发布
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()

                // 支持的通讯协议集合
                .protocols(new HashSet<>(Arrays.asList("http", "https")))

                // 授权信息设置，必要的header token等认证信息
                .securitySchemes(Collections.singletonList(new ApiKey("BASE_TOKEN", "token", In.HEADER.toValue())))

                // 授权信息全局应用
                .securityContexts(Collections.singletonList(
                        SecurityContext.builder()
                                .securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")})))
                                .build()
                ));
    }

    /**
     * API 页面上半部分展示信息
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title(title + " Api Doc")
                .description(description)
                .contact(new Contact("xxx", null, "xxx@mail.com"))
                .version(version)
                .build();
    }

    /**
     * 通用拦截器排除swagger设置，所有拦截器都会自动加swagger相关的资源排除信息
     */
    @SuppressWarnings("unchecked")
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        try {
            Field registrationsField = FieldUtils.getField(InterceptorRegistry.class, "registrations", true);
            List<InterceptorRegistration> registrations = (List<InterceptorRegistration>) ReflectionUtils.getField(registrationsField, registry);
            if (registrations != null) {
                for (InterceptorRegistration interceptorRegistration : registrations) {
                    interceptorRegistration
                            .excludePathPatterns("/swagger**/**")
                            .excludePathPatterns("/webjars/**")
                            .excludePathPatterns("/v3/**")
                            .excludePathPatterns("/doc.html");
                }
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }

}

3.添加application.yml配置

代码如下：

uhu:
  swagger:
    enable: true
    title: ${spring.application.name}
    version: 1.0.0
    description: 企业合规管理系统接口文档
    scanPackage: com.uhu
    host: http://localhost:${server.port}

4.查看是否整合成功

项目启动，访问 http://localhost:port/context-path/swagger-ui.html

5.常用注解

注解	注解说明	用法
@Api	类注解，用于给控制器取别名
@ApiOperation	常用来描述方法
@ApiModel和@ApiModelProperty	描述请求响应描述
@ApiParam	路径参数注解
@ApiImplicitParam和@ApiImplicitParams	描述方法参数

6.swagger美化

添加美化依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>

添加yml配置

knife4j:
  enable: true
  basic:
    enable: true
    username: admin
    password: admin
  setting:
    language: zh-CN

重启服务
访问 http://localhost:port/context-path/doc.html

---

总结

通过集成 Swagger3，我们可以方便地生成接口文档，使得前后端开发协同更加高效，通过knife4j进行美化后的页面更加适合国人的阅读习惯。
以上就是SpringBoot整合Swagger3的方式，是不是很简单，赶紧用起来吧！！！