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

SpringBoot3.3集成knif4j-swagger文档方式和使用案例

news 2025/7/13 4:01:53

springboot3 集成 knif4j ：

访问地址：

swagger 接口文档默认地址：http://localhost:8080/swagger-ui.html#

Knife4j 接口文档默认地址：http://127.0.0.1:8080/doc.html

Maven:

    <dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.4.0</version></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId><version>3.3.0</version></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-gateway-spring-boot-starter</artifactId><version>${knife4j-openapi3.version}</version></dependency>

基础微服务配置：


knife4j:# 开启增强配置enable: truebasic:enable: true# Basic认证用户名username: babasic# Basic认证密码password: BaBasic123!@#plm## 开启生产环境屏蔽，一定要先开启knife4j增强才会生效## You do not have permission to access this pageproduction: false

网关配置：

knife4j:gateway:enabled: true# 排序规则(tag/operation排序自4.2.0版本新增)# 取值：alpha-默认排序规则，官方swagger-ui默认实现,order-Knife4j提供的增强排序规则，开发者可扩展x-order，根据数值来自定义排序tags-sorter: orderoperations-sorter: order# 指定服务发现的模式聚合微服务文档strategy: manualroutes:- name: App1服务# 子服务存在其他分组情况，聚合其他分组url: /app1/v3/api-docs# 服务名称(Optional)service-name: baian-cloud-test-app1# 路由前缀context-path: /app1# 排序order: 1- name: App2服务# 子服务存在其他分组情况，聚合其他分组url: /app2/v3/api-docs# 服务名称(Optional)service-name: baian-cloud-test-app2# 路由前缀context-path: /app2# 排序order: 2- name: App3服务# 子服务存在其他分组情况，聚合其他分组url: /app3/v3/api-docs# 服务名称(Optional)service-name: baian-cloud-test-app3# 路由前缀context-path: /app3# 排序order: 3

全局添加自定义头

package com.baian.common.core.config;import io.swagger.v3.oas.models.Operation;
import io.swagger.v3.oas.models.media.Schema;
import io.swagger.v3.oas.models.parameters.HeaderParameter;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import lombok.extern.slf4j.Slf4j;
import org.springdoc.core.customizers.GlobalOpenApiCustomizer;
import org.springdoc.core.customizers.GlobalOperationCustomizer;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;
import org.springframework.web.method.HandlerMethod;import java.util.List;/*** @program: baian-cloud* @description: 为每个接口添加鉴权* @author: <航迹者-694204477@qq.com>* @create: 2024-07-02 10:21**/
@Slf4j
@Configuration
public class Knife4jOperationCustomizer {@Value("${sa-token.token-name:Authorization}")private String securityHeaderName;@Beanpublic GlobalOpenApiCustomizer orderGlobalOpenApiCustomizer() {return openApi -> {// 全局添加鉴权参数if (openApi.getPaths() != null) {HeaderParameter parametersItem = new HeaderParameter();parametersItem.setName(securityHeaderName);parametersItem.setRequired(false);Schema<String> schema = new Schema<>();schema.setType("string");parametersItem.setSchema(schema);openApi.getPaths().forEach((s, pathItem) -> {pathItem.readOperations().forEach(operation -> {// 为所有接口添加请求头operation.addParametersItem(parametersItem);// 为所有接口添加鉴权
//                        operation.addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION));});});}};}
}// https://doc.xiaominfo.com/docs/blog/add-authorization-header

注解：Springfox改用Springdoc后，注解改变：

@Api → @Tag@ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden@ApiImplicitParam → @Parameter@ApiImplicitParams → @Parameters@ApiModel → @Schema@ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)@ApiModelProperty → @Schema@ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")@ApiParam → @Parameter@ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

实用新增注解：

@ParameterObject

案例

@Tag(name = "用户接口")
@RestController
@RequestMapping("sys/user")
public class SysUserController {@Resourceprivate ISysUserService sysUserService;@Operation(summary = "分页查询")@GetMapping("page")public AjaxResult queryPage(@ParameterObject SysUserPageDTO dto) {PageInfo page = sysUserService.queryPage(dto);return AjaxResult.success(page);}@Operation(summary = "详情")@GetMapping("{id}")public AjaxResult queryInfo(@PathVariable Long id) {SysUserDTO dto = sysUserService.queryById(id);return AjaxResult.success(dto);}@Operation(summary = "新增")@PostMappingpublic AjaxResult save(@RequestBody SysUserDTO dto) {Long id = sysUserService.saveInfo(dto);return AjaxResult.success(id);}
}

@Getter
@Setter
@TableName("user")
@Schema(name = "User", description = "$!{table.comment}")
public class User implements Serializable {private static final long serialVersionUID = 1L;@Schema(description = "主键")@TableId("id")private Long id;@Schema(description = "用户名")@TableField("name")private String name;@Schema(description = "手机号")@TableField("phone")private String phone;@Schema(description = "性别")@TableField("sex")private String sex;@Schema(description = "状态 0:禁用，1:正常")@TableField("status")private Integer status;
}

其他参考：

https://gitee.com/-/ide/project/xiaoym/swagger-bootstrap-ui-demo/edit/master/-/knife4j-spring-boot3-demo/src/main/java/com/github/xiaoymin/boot3/config/SwaggerConfig.java

https://blog.csdn.net/m0_74055560/article/details/134348304

福利配置：自动转发。

package com.baian.common.core.config;import io.undertow.servlet.spec.HttpServletRequestImpl;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;import java.io.IOException;/*** @program: baian-cloud* @description: resource* @author: <航迹者-694204477@qq.com>* @create: 2024-07-02 08:51**/
@RestController
@Slf4j
public class BaiAnResourceCtl {@GetMapping("/")public void context(HttpServletRequest request, HttpServletResponse response) throws IOException {log.error("=====baian-cloud-common-web-core=======com.baian.common.core.config.BaiAnResourceCtl=================默认根path/====重定向到/doc.html==========");if (request instanceof HttpServletRequestImpl undertow) {String resolvedPath = undertow.getExchange().getResolvedPath();response.sendRedirect(resolvedPath + "/doc.html");return;}response.sendRedirect("/doc.html");}}