SpringBoot 集成Swagger3

说明：

1）、本文使用Spring2 集成Swagger3，本想使用Springboot3+ jdk 17 集成Swagger3, 但是搜了一些资料，Spring 想引用swagger3 需要依赖降级使用Spring2 版本，不然会出现下图的报错信息，或者使用Spring3 + springdoc 实现swagger的功能，可看SpringBoot3 集成Springdoc 实现Swagger3功能-CSDN博客；

2）、本文功能可通过配置文件实现swagger的开启与关闭，默认token的开启、设置

1、引包

 <parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>2.5.6</version></parent><properties><maven.compiler.source>17</maven.compiler.source><maven.compiler.target>17</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><maven.compiler.source>${java.version}</maven.compiler.source><maven.compiler.target>${java.version}</maven.compiler.target><springfox.swagger3.version>3.0.0</springfox.swagger3.version></properties><dependencies><dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>${springfox.swagger3.version}</version></dependency><!-- 美化引用--><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.3</version></dependency></dependencies>

2、配置

import com.google.common.collect.Sets;
import io.swagger.annotations.ApiOperation;
import io.swagger.models.auth.In;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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.util.ArrayList;
import java.util.List;/*** Swagger3* 目前springboot3对swagger3 版本有要求，使用3需要Springboot降到2* 原生地址 http://www.xx.xx/swagger-ui/index.html* 美化地址 http://www.xx.xx/doc.html* swagger2 地址http://www.xx.xx/swagger-ui.html*/
@EnableOpenApi
@Configuration
public class Swagger3 {@Value("${swagger.enable}")private boolean enableSwagger = true;@Value("${swagger.token}")private String token = "X_TOKEN";@Value("${swagger.enable-token}")private boolean enableToken = true;/*** API 页面展示信息*/private ApiInfo apiInfo() {return new ApiInfoBuilder()// 标题.title("接口文档")// 描述.description("测试接口文档，发布: http://www.xx.xx/swagger-ui/index.html")// 作者.contact(new Contact("zc", "", "xxx@qq.com"))// 版本.version("版本号:V1.0").build();}@Beanpublic Docket createRestApi() {Docket docket = new Docket(DocumentationType.OAS_30).pathMapping("/")// 定义是否开启swagger.enable(enableSwagger)// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）.apiInfo(apiInfo())// 设置哪些接口暴露给Swagger展示.select()// 扫描所有有注解的api.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 扫描指定包中的swagger注解
//				.apis(RequestHandlerSelectors.basePackage("com.zc.controller")).paths(PathSelectors.any()).build()// 支持的通讯协议集合.protocols(Sets.newHashSet("http", "https"));if (enableToken) {// 授权信息设置，必要的header token等认证信息docket.securitySchemes(securitySchemes())// 授权信息全局应用.securityContexts(securityContexts());}return docket;}/*** 设置授权信息*/private List<SecurityScheme> securitySchemes() {List<SecurityScheme> securitySchemes = new ArrayList<>();securitySchemes.add(new ApiKey(token, token, In.HEADER.toValue()));return securitySchemes;}/*** 授权信息全局应用*/private List<SecurityContext> securityContexts() {List<SecurityContext> securityContexts = new ArrayList<>();securityContexts.add(SecurityContext.builder().securityReferences(securityReferences()).forPaths(PathSelectors.any()).build());return securityContexts;}private List<SecurityReference> securityReferences(){List<SecurityReference> securityReferences = new ArrayList<>();securityReferences.add(new SecurityReference(token,new AuthorizationScope[]{new AuthorizationScope("global", "accessEverything")}));return securityReferences;}
}

3、配置文件说明

swagger:enable: trueenable-token: truetoken: X_TOKEN

4、controller

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;/*** @author zc* @date 2024/2/23 13:29* @desc*/
@RestController
@RequestMapping("/test")
@Api(value = "测试接口", tags = "测试接口")
public class TestController {@GetMapping("/get")@ApiOperation(value = "webClient", notes = "webClient")public String test(){return "ok";}
}