当前位置： 首页 > ai >正文

SpringBoot2.3.1集成Knife4j接口文档

ai 2025/7/13 7:26:50

首先要查看项目中pom文件里面有没有swagger和knife4j的依赖，如果有的话删除，加入以下依赖

<!-- swagger --><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-spring-boot-starter</artifactId><version>${knife4j.version}</version><exclusions><exclusion><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-webmvc-core</artifactId></exclusion><exclusion><groupId>io.springfox</groupId><artifactId>*</artifactId></exclusion></exclusions></dependency><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-ui</artifactId><version>${springdoc.version}</version></dependency></dependencies>

然后在下面文件中加入配置初始化语句:

#################### 接口文档配置 ####################
springdoc.api-docs.enabled= true
springdoc.api-docs.path= /v3/api-docs
springdoc.swagger-ui.enabled= true
springdoc.swagger-ui.path= /swagger-ui
springdoc.default-flat-param-object= trueknife4j.enable= false
knife4j.setting.language= zh_cn

新建swagger的config类，内容如下：

SwaggerProperties

package com.todod.config.swagger;import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;import javax.validation.constraints.NotEmpty;/*** Swagger 配置属性** @author admin*/
@ConfigurationProperties("base.swagger")
@Data
public class SwaggerProperties {/*** 标题*/@NotEmpty(message = "标题不能为空")private String title;/*** 描述*/@NotEmpty(message = "描述不能为空")private String description;/*** 作者*/@NotEmpty(message = "作者不能为空")private String author;/*** 版本*/@NotEmpty(message = "版本不能为空")private String version;/*** url*/@NotEmpty(message = "扫描的 package 不能为空")private String url;/*** email*/@NotEmpty(message = "扫描的 email 不能为空")private String email;/*** license*/@NotEmpty(message = "扫描的 license 不能为空")private String license;/*** license-url*/@NotEmpty(message = "扫描的 license-url 不能为空")private String licenseUrl;}

BaseSwaggerAutoConfiguration
package com.todod.config.swagger;import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.media.IntegerSchema;
import io.swagger.v3.oas.models.media.StringSchema;
import io.swagger.v3.oas.models.parameters.Parameter;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springdoc.core.*;
import org.springdoc.core.customizers.OpenApiBuilderCustomizer;
import org.springdoc.core.customizers.ServerBaseUrlCustomizer;
import org.springdoc.core.providers.JavadocProvider;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import org.springframework.http.HttpHeaders;import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;/*** Swagger 自动配置类，基于 OpenAPI + Springdoc 实现。** 友情提示：* 1. Springdoc 文档地址：<a href="https://github.com/springdoc/springdoc-openapi">仓库</a>* 2. Swagger 规范，于 2015 更名为 OpenAPI 规范，本质是一个东西** @author admin*/
@Configuration
@ConditionalOnClass({OpenAPI.class})
@EnableConfigurationProperties(SwaggerProperties.class)
@ConditionalOnProperty(prefix = "springdoc.api-docs", name = "enabled", havingValue = "true", matchIfMissing = true) // 设置为 false 时，禁用
public class BaseSwaggerAutoConfiguration {public static final String HEADER_TENANT_ID = "tenant-id";// ========== 全局 OpenAPI 配置 ==========@Beanpublic OpenAPI createApi(SwaggerProperties properties) {Map<String, SecurityScheme> securitySchemas = buildSecuritySchemes();OpenAPI openAPI = new OpenAPI()// 接口信息.info(buildInfo(properties))// 接口安全配置.components(new Components().securitySchemes(securitySchemas)).addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION));securitySchemas.keySet().forEach(key -> openAPI.addSecurityItem(new SecurityRequirement().addList(key)));return openAPI;}/*** API 摘要信息*/private Info buildInfo(SwaggerProperties properties) {return new Info().title(properties.getTitle()).description(properties.getDescription()).version(properties.getVersion()).contact(new Contact().name(properties.getAuthor()).url(properties.getUrl()).email(properties.getEmail())).license(new License().name(properties.getLicense()).url(properties.getLicenseUrl()));}/*** 安全模式，这里配置通过请求头 Authorization 传递 token 参数*/private Map<String, SecurityScheme> buildSecuritySchemes() {Map<String, SecurityScheme> securitySchemes = new HashMap<>();SecurityScheme securityScheme = new SecurityScheme().type(SecurityScheme.Type.APIKEY) // 类型.name(HttpHeaders.AUTHORIZATION) // 请求头的 name.in(SecurityScheme.In.HEADER); // token 所在位置securitySchemes.put(HttpHeaders.AUTHORIZATION, securityScheme);return securitySchemes;}/*** 自定义 OpenAPI 处理器*/@Bean@Primary // 目的：以我们创建的 OpenAPIService Bean 为主，避免一键改包后，启动报错！public OpenAPIService openApiBuilder(Optional<OpenAPI> openAPI,SecurityService securityParser,SpringDocConfigProperties springDocConfigProperties,PropertyResolverUtils propertyResolverUtils,Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomizers,Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomizers,Optional<JavadocProvider> javadocProvider) {return new OpenAPIService(openAPI, securityParser, springDocConfigProperties,propertyResolverUtils, openApiBuilderCustomizers, serverBaseUrlCustomizers, javadocProvider);}// ========== 分组 OpenAPI 配置 ==========/*** 所有模块的 API 分组*/@Beanpublic GroupedOpenApi allGroupedOpenApi() {return buildGroupedOpenApi("all", "");}public static GroupedOpenApi buildGroupedOpenApi(String group) {return buildGroupedOpenApi(group, group);}public static GroupedOpenApi buildGroupedOpenApi(String group, String path) {return GroupedOpenApi.builder().group(group).pathsToMatch("/admin-api/" + path + "/**", "/" + path + "/**").addOperationCustomizer((operation, handlerMethod) -> operation.addParametersItem(buildTenantHeaderParameter()).addParametersItem(buildSecurityHeaderParameter())).build();}/*** 构建 Tenant 租户编号请求头参数** @return 多租户参数*/private static Parameter buildTenantHeaderParameter() {return new Parameter().name(HEADER_TENANT_ID) // header 名.description("租户编号") // 描述.in(String.valueOf(SecurityScheme.In.HEADER)) // 请求 header.schema(new IntegerSchema()._default(1L).name(HEADER_TENANT_ID).description("租户编号")); // 默认：使用租户编号为 1}/*** 构建 Authorization 认证请求头参数** 解决 Knife4j <a href="https://gitee.com/xiaoym/knife4j/issues/I69QBU">Authorize 未生效，请求header里未包含参数</a>** @return 认证参数*/private static Parameter buildSecurityHeaderParameter() {return new Parameter().name(HttpHeaders.AUTHORIZATION) // header 名.description("认证 Token") // 描述.in(String.valueOf(SecurityScheme.In.HEADER)) // 请求 header.schema(new StringSchema()._default("Bearer test1").name(HEADER_TENANT_ID).description("认证 Token")); // 默认：使用用户编号为 1}}

新建WebAppConfig类来控制./doc.html可以访问

代码如下：

package com.todod.config;import com.todod.interceptor.LoginInterceptor;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.CacheControl;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;import java.util.concurrent.TimeUnit;@Configuration
public class WebAppConfig implements WebMvcConfigurer {@Value("${file.upload.path}")private String uploadPath; // 文件路径@Value("${file.upload.mapping}")private String showPath; // 映射路径@Autowiredprivate LoginInterceptor loginInterceptor;/*** interceptor配置*/@Overridepublic void addInterceptors(InterceptorRegistry registry) {registry.addInterceptor(loginInterceptor)// 添加需要验证登录用户操作权限的请求.addPathPatterns("/**")// 排除不需要验证登录用户操作权限的请求.excludePathPatterns("/user/login/**", "/user/logout/**","/apiDemo/doGet/**","/ltcloud/user/getAllUser","/ltcloud/frequency/getFrequencyById","/empower/**");}@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {String a = showPath + "**";String b = "file:" + uploadPath;registry.addResourceHandler(a).addResourceLocations(b).setCacheControl(CacheControl.maxAge(2, TimeUnit.DAYS));registry.addResourceHandler("/doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}
}

前端：

<template><div><i-frame v-if="!loading" :src="url" /></div>
</template>
<script>
import iFrame from "@/components/iFrame/index";
import { getConfigKey } from "@/api/infra/config";
export default {name: "InfraSwagger",components: { iFrame },data() {return {url: process.env.VUE_APP_BASE_API + "doc.html", // Knife4j UIloading: true};},created() {this.url =process.env.VUE_APP_BASE_API + "doc.html"this.loading = false;}
};
</script>

到此配置完毕，范围localhost:后端端口/doc.html

注：

1.BaseSwaggerAutoConfiguration类中的buildGroupedOpenApi方法可以控制显示哪些controller里的接口：

public static GroupedOpenApi buildGroupedOpenApi(String group, String path) {return GroupedOpenApi.builder().group(group).pathsToMatch("/admin-api/" + path + "/**", "/" + path + "/**").addOperationCustomizer((operation, handlerMethod) -> operation.addParametersItem(buildTenantHeaderParameter()).addParametersItem(buildSecurityHeaderParameter())).build();}

2.在controller上面加tag注解可以给controller接口起名字，改变英文显示

operation则会改变接口的名字

http://www.xdnf.cn/news/10805.html

相关文章：

  • GirtHub访问不了解决方案
  • 【亲测有效】Mybatis-Plus中更新字段为null
  • android FragmentManager 删除所有Fragment 重建
  • EscapeX：去中心化游戏，开启极限娱乐新体验
  • Mybatis--创建mapper接口
  • IP话机和APP拨打电话的区别
  • Go语言学习--＞从零开始搭建环境
  • FreeRTOS的简单介绍
  • 从0开始使用 Vue3 和 TypeScript 搭建项目详细教程
  • 1.Nodejs开发注意和前端区别
  • C语言：数据在内存中的存储
  • 关于list集合排序的常见方法
  • 《TCP/IP 详解 卷1：协议》第5章：Internet协议
  • 红黑树与红黑树的插入——用C++实现
  • Python----循环神经网络（BiLSTM：双向长短时记忆网络）
  • Rust 学习笔记：使用 cargo install 安装二进制 crate
  • 【氮化镓】GaN HMETs器件物理失效分析进展
  • NVIDIA CUDA Toolkit安装
  • 遥感影像建筑物变化检测
  • 前端与后端
  • [Java 基础]Java 是什么
  • 帝可得 - 设备管理
  • 谷歌地图高清卫星地图2026中文版下载|谷歌地图3D卫星高清版 V7.3.6.9796 最新免费版下载 - 前端工具导航
  • 阿里云为何，一个邮箱绑定了两个账号
  • Go语言学习--＞第一个go程序--hello world!
  • xTimerChangePeriod无需先Stop
  • Ros(launch一键打开？)
  • 永磁同步电机无速度算法--互补滑模观测器
  • Unity-UI组件详解
  • 嵌入式复习小练