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");}}