feat: 更新配置文件和代码，优化Swagger文档和负载均衡支持

fix: 网关聚合文档实现
fix: 放行文档
2026-01-08 01:15:56 +08:00 · 2026-01-08 00:50:32 +08:00 · 2026-01-08 00:50:12 +08:00 · 2026-01-08 00:48:37 +08:00
26 changed files with 264 additions and 74 deletions
--- a/.idea/CoolRequestCommonStatePersistent.xml
+++ b/.idea/CoolRequestCommonStatePersistent.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
  <component name="CoolRequestCommonStatePersistent">
-    <option name="searchCache" value="系统内部异常" />
+    <option name="searchCache" value="UserRegisterRequestDTO" />
  </component>
 </project>
--- a/.idea/dataSources.xml
+++ b/.idea/dataSources.xml
@@ -25,29 +25,5 @@
      <jdbc-url>jdbc:mysql://10.0.0.10/aioj_dev</jdbc-url>
      <working-dir>$ProjectFileDir$</working-dir>
    </data-source>
-    <data-source source="LOCAL" name="jdbc:mysql://10.0.0.10/aioj_dev [DEBUG]" group="AIOJAdminApplication" uuid="41a79ccb-ccd0-4180-92f5-e2ef6a45eb88">
-      <driver-ref>mysql.8</driver-ref>
-      <synchronize>true</synchronize>
-      <imported>true</imported>
-      <jdbc-driver>com.mysql.cj.jdbc.Driver</jdbc-driver>
-      <jdbc-url>jdbc:mysql://10.0.0.10/aioj_dev</jdbc-url>
-      <working-dir>$ProjectFileDir$</working-dir>
-    </data-source>
-    <data-source source="LOCAL" name="jdbc:mysql://10.0.0.10/aioj_dev [DEBUG]" group="AIOJAuthApplication" uuid="25412482-92b5-469f-ab7e-552bb8d40a92">
-      <driver-ref>mysql.8</driver-ref>
-      <synchronize>true</synchronize>
-      <imported>true</imported>
-      <jdbc-driver>com.mysql.cj.jdbc.Driver</jdbc-driver>
-      <jdbc-url>jdbc:mysql://10.0.0.10/aioj_dev</jdbc-url>
-      <working-dir>$ProjectFileDir$</working-dir>
-    </data-source>
-    <data-source source="LOCAL" name="jdbc:mysql://10.0.0.10/aioj_dev [DEBUG]" group="UserServiceApplication" uuid="b7567e65-352c-4868-8b20-267b4c439f0e">
-      <driver-ref>mysql.8</driver-ref>
-      <synchronize>true</synchronize>
-      <imported>true</imported>
-      <jdbc-driver>com.mysql.cj.jdbc.Driver</jdbc-driver>
-      <jdbc-url>jdbc:mysql://10.0.0.10/aioj_dev</jdbc-url>
-      <working-dir>$ProjectFileDir$</working-dir>
-    </data-source>
  </component>
 </project>
--- a/.idea/db-forest-config.xml
+++ b/.idea/db-forest-config.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
  <component name="db-tree-configuration">
-    <option name="data" value="1:0:AIOJAdminApplication&#10;4:0:UserServiceApplication&#10;7:0:AIOJAuthApplication&#10;----------------------------------------&#10;2:1:43cc61de-66e1-44cc-b4a2-b24d7e03b490&#10;3:1:41a79ccb-ccd0-4180-92f5-e2ef6a45eb88&#10;5:4:903d03c4-df11-4cf8-939a-3e5fba0ab207&#10;6:4:b7567e65-352c-4868-8b20-267b4c439f0e&#10;8:7:2fd8684a-b9aa-4507-abb0-f7c259d91286&#10;9:7:25412482-92b5-469f-ab7e-552bb8d40a92&#10;" />
+    <option name="data" value="1:0:AIOJAdminApplication&#10;3:0:UserServiceApplication&#10;5:0:AIOJAuthApplication&#10;----------------------------------------&#10;2:1:43cc61de-66e1-44cc-b4a2-b24d7e03b490&#10;4:3:903d03c4-df11-4cf8-939a-3e5fba0ab207&#10;6:5:2fd8684a-b9aa-4507-abb0-f7c259d91286&#10;" />
  </component>
 </project>
--- a/.idea/encodings.xml
+++ b/.idea/encodings.xml
@@ -1,6 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
  <component name="Encoding">
+    <file url="file://$PROJECT_DIR$/../../../../Windows/System32/src/main/java" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/../../../../Windows/System32/src/main/resources" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/aioj-backend-ai-service/src/main/java" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/aioj-backend-ai-service/src/main/resources" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/aioj-backend-auth/src/main/java" charset="UTF-8" />
@@ -14,6 +16,7 @@
    <file url="file://$PROJECT_DIR$/aioj-backend-common/aioj-backend-common-mybatis/src/main/java" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/aioj-backend-common/aioj-backend-common-starter/src/main/java" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/aioj-backend-common/aioj-backend-common-starter/src/main/resources" charset="UTF-8" />
+    <file url="file://$PROJECT_DIR$/aioj-backend-common/aioj-backend-common-swagger/src/main/java" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/aioj-backend-common/src/main/java" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/aioj-backend-common/src/main/resources" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/aioj-backend-gateway/src/main/java" charset="UTF-8" />
@@ -33,7 +36,5 @@
    <file url="file://$PROJECT_DIR$/aioj-backend-user-service/src/main/resources" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/src/main/java" charset="UTF-8" />
    <file url="file://$PROJECT_DIR$/src/main/resources" charset="UTF-8" />
-    <file url="file://$PROJECT_DIR$/../../../../Windows/System32/src/main/java" charset="UTF-8" />
-    <file url="file://$PROJECT_DIR$/../../../../Windows/System32/src/main/resources" charset="UTF-8" />
  </component>
 </project>
--- a/aioj-backend-auth/pom.xml
+++ b/aioj-backend-auth/pom.xml
@@ -19,6 +19,32 @@
    </properties>

    <dependencies>
+        <!-- SpringDoc OpenAPI - 显式指定版本以兼容 Spring Boot 3.5.x -->
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+            <version>2.8.4</version>
+        </dependency>
+        <dependency>
+            <groupId>com.github.xiaoymin</groupId>
+            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
+            <version>4.5.0</version>
+            <exclusions>
+                <exclusion>
+                    <groupId>org.springdoc</groupId>
+                    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>org.springdoc</groupId>
+                    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>org.springdoc</groupId>
+                    <artifactId>springdoc-openapi-starter-common</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
+
        <!-- 核心模块 -->
        <dependency>
            <groupId>cn.meowrain</groupId>
@@ -107,12 +133,6 @@
            <artifactId>spring-boot-starter-data-redis</artifactId>
        </dependency>

-        <!-- API文档 -->
-        <dependency>
-            <groupId>com.github.xiaoymin</groupId>
-            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
-        </dependency>
-
        <!-- 开发工具 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
--- a/aioj-backend-auth/src/main/java/cn/meowrain/aioj/backend/auth/config/SecurityConfiguration.java
+++ b/aioj-backend-auth/src/main/java/cn/meowrain/aioj/backend/auth/config/SecurityConfiguration.java
@@ -27,7 +27,7 @@ public class SecurityConfiguration {
 			.sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
 			.authorizeHttpRequests(auth -> auth
 				.requestMatchers("/v1/auth/**", "/oauth2/**", "/.well-known/**", "/doc.html", "/swagger-ui/**",
-						"/swagger-resources/**", "/webjars/**", "/v3/api-docs/**", "/favicon.ico")
+						"/swagger-resources/**", "/webjars/**", "/v3/api-docs/**", "/v3/api-docs", "/favicon.ico")
 				.permitAll()
 				.anyRequest()
 				.authenticated())
--- a/aioj-backend-auth/src/main/java/cn/meowrain/aioj/backend/auth/config/SwaggerConfiguration.java
+++ b/aioj-backend-auth/src/main/java/cn/meowrain/aioj/backend/auth/config/SwaggerConfiguration.java
@@ -25,7 +25,7 @@ public class SwaggerConfiguration implements ApplicationRunner {

 	@Bean
 	public OpenAPI customerOpenAPI() {
-		return new OpenAPI().info(new Info().title("AIOJ-renz微服务✨")
+		return new OpenAPI().info(new Info().title("AIOJ-认证微服务✨")
 			.description("用户认证功能")
 			.version("v1.0.0")
 			.contact(new Contact().name("meowrain").email("meowrain@126.com"))
--- a/aioj-backend-auth/src/main/java/cn/meowrain/aioj/backend/auth/filter/JwtAuthenticationFilter.java
+++ b/aioj-backend-auth/src/main/java/cn/meowrain/aioj/backend/auth/filter/JwtAuthenticationFilter.java
@@ -99,7 +99,8 @@ public class JwtAuthenticationFilter extends OncePerRequestFilter {
 		// 跳过不需要JWT验证的路径
 		return path.startsWith("/v1/auth/") || path.startsWith("/doc.html") || path.startsWith("/swagger-ui/")
 				|| path.startsWith("/swagger-resources/") || path.startsWith("/webjars/")
-				|| path.startsWith("/v3/api-docs/") || path.equals("/favicon.ico");
+				|| path.startsWith("/v3/api-docs") || path.equals("/favicon.ico")
+				|| path.contains("/v3/api-docs");
 	}

 }
--- a/aioj-backend-auth/src/main/resources/application.yml
+++ b/aioj-backend-auth/src/main/resources/application.yml
@@ -21,8 +21,8 @@ springdoc:
    operations-sorter: alpha
  group-configs:
    - group: 'default'
-      paths-to-match: '/**'
-      packages-to-scan: cn.meowrain.aioj.backend.userservice.controller
+      paths-to-match: '/api/**'
+      packages-to-scan: cn.meowrain.aioj.backend.auth.controller
 knife4j:
  basic:
    enable: true
--- a/aioj-backend-common/aioj-backend-common-bom/pom.xml
+++ b/aioj-backend-common/aioj-backend-common-bom/pom.xml
@@ -62,13 +62,6 @@
            </dependency>


-            <!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-openapi3-jakarta-spring-boot-starter -->
-            <dependency>
-                <groupId>com.github.xiaoymin</groupId>
-                <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
-                <version>4.5.0</version>
-            </dependency>
-
            <!-- OAuth2 Client -->
            <!-- https://mvnrepository.com/artifact/org.springframework.security/spring-security-oauth2-client -->
            <!-- https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-oauth2-client -->
--- a/aioj-backend-common/aioj-backend-common-core/src/main/java/cn/meowrain/aioj/backend/framework/core/web/Result.java
+++ b/aioj-backend-common/aioj-backend-common-core/src/main/java/cn/meowrain/aioj/backend/framework/core/web/Result.java
@@ -1,5 +1,6 @@
 package cn.meowrain.aioj.backend.framework.core.web;

+import com.fasterxml.jackson.annotation.JsonIgnore;
 import lombok.Data;
 import lombok.experimental.Accessors;

@@ -40,6 +41,7 @@ public class Result<T> implements Serializable {
 	 * 返回是否是正确响应
 	 * @return boolean
 	 */
+	@JsonIgnore
 	public boolean isSuccess() {
 		return SUCCESS_CODE.equals(code);
 	}
@@ -48,6 +50,7 @@ public class Result<T> implements Serializable {
 	 * 返回是否是错误响应
 	 * @return boolean
 	 */
+	@JsonIgnore
 	public boolean isFail() {
 		return !isSuccess();
 	}
--- a/aioj-backend-common/aioj-backend-common-mybatis/pom.xml
+++ b/aioj-backend-common/aioj-backend-common-mybatis/pom.xml
@@ -44,11 +44,6 @@
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
        </dependency>
-        <!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-openapi3-jakarta-spring-boot-starter -->
-        <dependency>
-            <groupId>com.github.xiaoymin</groupId>
-            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
-        </dependency>

        <dependency>
            <groupId>org.springframework.security</groupId>
--- a/aioj-backend-common/aioj-backend-common-mybatis/src/main/java/cn/meowrain/backend/common/mybaits/base/BaseEntity.java
+++ b/aioj-backend-common/aioj-backend-common-mybatis/src/main/java/cn/meowrain/backend/common/mybaits/base/BaseEntity.java
@@ -2,7 +2,6 @@ package cn.meowrain.backend.common.mybaits.base;

 import com.baomidou.mybatisplus.annotation.FieldFill;
 import com.baomidou.mybatisplus.annotation.TableField;
-import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Getter;
 import lombok.Setter;

@@ -23,28 +22,24 @@ public class BaseEntity implements Serializable {
 	/**
 	 * 创建者
 	 */
-	@Schema(description = "创建人")
 	@TableField(fill = FieldFill.INSERT)
 	private String createBy;

 	/**
 	 * 创建时间
 	 */
-	@Schema(description = "创建时间")
 	@TableField(fill = FieldFill.INSERT)
 	private LocalDateTime createTime;

 	/**
 	 * 更新者
 	 */
-	@Schema(description = "更新人")
 	@TableField(fill = FieldFill.INSERT_UPDATE)
 	private String updateBy;

 	/**
 	 * 更新时间
 	 */
-	@Schema(description = "更新时间")
 	@TableField(fill = FieldFill.INSERT_UPDATE)
 	private LocalDateTime updateTime;

--- a/aioj-backend-common/aioj-backend-common-swagger/pom.xml
+++ b/aioj-backend-common/aioj-backend-common-swagger/pom.xml
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>cn.meowrain</groupId>
+        <artifactId>aioj-backend-common</artifactId>
+        <version>1.0-SNAPSHOT</version>
+    </parent>
+
+    <groupId>cn.meowrain.aioj.backend.common.swagger</groupId>
+    <artifactId>aioj-backend-common-swagger</artifactId>
+
+    <properties>
+        <maven.compiler.source>17</maven.compiler.source>
+        <maven.compiler.target>17</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+</project>
--- a/aioj-backend-common/aioj-backend-common-swagger/src/main/java/cn/meowrain/aioj/backend/common/swagger/Main.java
+++ b/aioj-backend-common/aioj-backend-common-swagger/src/main/java/cn/meowrain/aioj/backend/common/swagger/Main.java
@@ -0,0 +1,17 @@
+package cn.meowrain.aioj.backend.common.swagger;
+
+//TIP 要<b>运行</b>代码，请按 <shortcut actionId="Run"/> 或
+// 点击装订区域中的 <icon src="AllIcons.Actions.Execute"/> 图标。
+public class Main {
+    public static void main(String[] args) {
+        //TIP 当文本光标位于高亮显示的文本处时按 <shortcut actionId="ShowIntentionActions"/>
+        // 查看 IntelliJ IDEA 建议如何修正。
+        System.out.printf("Hello and welcome!");
+
+        for (int i = 1; i <= 5; i++) {
+            //TIP 按 <shortcut actionId="Debug"/> 开始调试代码。我们已经设置了一个 <icon src="AllIcons.Debugger.Db_set_breakpoint"/> 断点
+            // 但您始终可以通过按 <shortcut actionId="ToggleLineBreakpoint"/> 添加更多断点。
+            System.out.println("i = " + i);
+        }
+    }
+}
--- a/aioj-backend-gateway/pom.xml
+++ b/aioj-backend-gateway/pom.xml
@@ -50,11 +50,10 @@
            <groupId>com.alibaba.csp</groupId>
            <artifactId>sentinel-datasource-extension</artifactId>
        </dependency>
-        <!--
-        https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-openapi3-jakarta-spring-boot-starter -->
+
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
-            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
+            <artifactId>knife4j-gateway-spring-boot-starter</artifactId>
            <version>4.5.0</version>
        </dependency>

@@ -80,5 +79,9 @@
                </exclusion>
            </exclusions>
        </dependency>
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-actuator</artifactId>
+        </dependency>
    </dependencies>
 </project>
--- a/aioj-backend-gateway/src/main/java/cn/meowrain/aioj/backend/gateway/config/GatewayConfiguration.java
+++ b/aioj-backend-gateway/src/main/java/cn/meowrain/aioj/backend/gateway/config/GatewayConfiguration.java
@@ -1,6 +1,7 @@
 package cn.meowrain.aioj.backend.gateway.config;

 import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.cloud.client.loadbalancer.LoadBalanced;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.web.reactive.function.client.WebClient;
@@ -13,9 +14,11 @@ import org.springframework.web.reactive.function.client.WebClient;
 public class GatewayConfiguration {

 	/**
-	 * WebClient Bean，用于服务间调用
+	 * 支持负载均衡的 WebClient Bean，用于服务间调用
+	 * 加上 @LoadBalanced 注解后可以使用 lb://service-name 格式的 URI
 	 */
 	@Bean
+	@LoadBalanced
 	public WebClient.Builder webClientBuilder() {
 		return WebClient.builder();
 	}
--- a/aioj-backend-gateway/src/main/java/cn/meowrain/aioj/backend/gateway/config/SwaggerDocPrinter.java
+++ b/aioj-backend-gateway/src/main/java/cn/meowrain/aioj/backend/gateway/config/SwaggerDocPrinter.java
@@ -0,0 +1,42 @@
+package cn.meowrain.aioj.backend.gateway.config;
+
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.ApplicationArguments;
+import org.springframework.boot.ApplicationRunner;
+import org.springframework.stereotype.Component;
+
+import java.net.InetAddress;
+
+/**
+ * 启动时打印 Swagger 文档地址
+ */
+@Slf4j
+@Component
+public class SwaggerDocPrinter implements ApplicationRunner {
+
+    @Value("${server.port:8080}")
+    private int port;
+
+    @Value("${server.servlet.context-path:}")
+    private String contextPath;
+
+    @Override
+    public void run(ApplicationArguments args) throws Exception {
+        String ip = InetAddress.getLocalHost().getHostAddress();
+        String ctx = contextPath == null ? "" : contextPath;
+        
+        String line = "=".repeat(60);
+        
+        log.info("\n" + line +
+                "\n  应用启动成功！Swagger 文档地址：" +
+                "\n" + line +
+                "\n  本地访问:    http://localhost:" + port + ctx + "/doc.html" +
+                "\n  网络访问:    http://" + ip + ":" + port + ctx + "/doc.html" +
+                "\n" + line +
+                "\n  API 文档资源:" +
+                "\n  - Knife4j UI:        http://localhost:" + port + ctx + "/doc.html" +
+                "\n  - Swagger Resources: http://localhost:" + port + ctx + "/swagger-resources" +
+                "\n" + line);
+    }
+}
--- a/aioj-backend-gateway/src/main/java/cn/meowrain/aioj/backend/gateway/filter/AuthGlobalFilter.java
+++ b/aioj-backend-gateway/src/main/java/cn/meowrain/aioj/backend/gateway/filter/AuthGlobalFilter.java
@@ -48,19 +48,19 @@ public class AuthGlobalFilter implements GlobalFilter, Ordered {
 		ServerHttpRequest request = exchange.getRequest();
 		String path = request.getURI().getPath();

-		log.info("Auth filter processing request: {}", path);
-		log.info("Loaded white list from config: {}", gatewayPropertiesConfiguration.getWhiteList());
+		log.info("🚀 网关拦截请求: {}", path);
+		log.debug("📋 白名单配置: {}", gatewayPropertiesConfiguration.getWhiteList());

 		// 检查是否在白名单中
 		if (isWhiteListPath(path)) {
-			log.info("Path {} is in whitelist, skip authentication", path);
+			log.info("✅ 路径 {} 在白名单中，跳过认证", path);
 			return chain.filter(exchange);
 		}

 		// 获取Authorization头
 		String authHeader = request.getHeaders().getFirst(HttpHeaders.AUTHORIZATION);
 		if (authHeader == null || !authHeader.startsWith("Bearer ")) {
-			log.warn("No valid authorization header found for path: {}", path);
+			log.warn("⚠️ 请求缺少有效的 Authorization 头: {}", path);
 			return handleUnauthorized(exchange);
 		}

@@ -70,15 +70,15 @@ public class AuthGlobalFilter implements GlobalFilter, Ordered {
 		return validateToken(token)
 			.flatMap(isValid -> {
 				if (isValid) {
-					log.info("Token validation successful for path: {}", path);
+					log.info("🔓 Token 验证成功: {}", path);
 					return chain.filter(exchange);
 				} else {
-					log.warn("Token validation failed for path: {}", path);
+					log.warn("🔒 Token 验证失败: {}", path);
 					return handleUnauthorized(exchange);
 				}
 			})
 			.onErrorResume(throwable -> {
-				log.error("Token validation error for path: {}", path, throwable);
+				log.error("❌ Token 验证异常: {}", path, throwable);
 				return handleUnauthorized(exchange);
 			});
 	}
@@ -105,7 +105,7 @@ public class AuthGlobalFilter implements GlobalFilter, Ordered {
 	private Mono<Boolean> validateToken(String token) {
 		return webClientBuilder.build()
 			.post()
-			.uri("lb://auth-service/v1/auth/validate")
+			.uri("lb://auth-service/api/v1/auth/validate")
 			.header(HttpHeaders.AUTHORIZATION, "Bearer " + token)
 			.contentType(MediaType.APPLICATION_JSON)
 			.retrieve()
@@ -116,7 +116,7 @@ public class AuthGlobalFilter implements GlobalFilter, Ordered {
 					Result result = objectMapper.readValue(response, Result.class);
 					return Objects.equals(result.getCode(), Result.SUCCESS_CODE);
 				} catch (JsonProcessingException e) {
-					log.error("Failed to parse auth response", e);
+					log.error("❌ 解析认证服务响应失败", e);
 					return false;
 				}
 			})
--- a/aioj-backend-gateway/src/main/resources/application-dev.yml
+++ b/aioj-backend-gateway/src/main/resources/application-dev.yml
@@ -51,16 +51,42 @@ aioj-backend-gateway:
    - /api/v1/question/detail/**
    - /actuator/health
    - /swagger-ui/**
+    - /doc.html
+    - /doc.html/**
+    - /webjars/**
+    - /v3/api-docs/**
+    - /**/v3/api-docs/**
+    - /auth-service/**
+    - /user-service/**

 logging:
  level:
    root: INFO
    # Nacos 相关日志
    com.alibaba.nacos: INFO
-    com.alibaba.cloud.nacos: DEBUG
+    com.alibaba.cloud.nacos: INFO
    # LoadBalancer 日志
-    org.springframework.cloud.loadbalancer: DEBUG
-    # Gateway 日志
-    org.springframework.cloud.gateway: DEBUG
+    org.springframework.cloud.loadbalancer: INFO
+    # Gateway 日志 - 改为 INFO 减少输出，需要调试时改回 DEBUG
+    org.springframework.cloud.gateway: INFO
    # 自定义过滤器日志
    cn.meowrain.aioj.backend.gateway: DEBUG
+
+
+knife4j:
+  gateway:
+    enabled: true
+    tags-sorter: alpha
+    operations-sorter: alpha
+    strategy: manual
+    routes:
+      - name: 认证服务
+        service-name: auth-service
+        url: /auth-service/api/v3/api-docs
+        context-path: /auth-service
+        order: 1
+      - name: 用户服务
+        service-name: user-service
+        url: /user-service/api/v3/api-docs
+        context-path: /user-service
+        order: 2
--- a/aioj-backend-gateway/src/main/resources/application.yml
+++ b/aioj-backend-gateway/src/main/resources/application.yml
@@ -11,6 +11,21 @@ spring:
      server:
        webflux:
          routes:
+            # auth服务 Swagger 文档路由
+            - id: auth-service-doc
+              uri: lb://auth-service
+              predicates:
+                - Path=/auth-service/**
+              filters:
+                - StripPrefix=1
+            # user服务 Swagger 文档路由
+            - id: user-service-doc
+              uri: lb://user-service
+              predicates:
+                - Path=/user-service/**
+              filters:
+                - StripPrefix=1
+            # auth业务接口
            - id: auth-service
              uri: lb://auth-service
              predicates:
--- a/aioj-backend-upms/aioj-backend-upms-api/pom.xml
+++ b/aioj-backend-upms/aioj-backend-upms-api/pom.xml
@@ -18,6 +18,32 @@
    </properties>

    <dependencies>
+        <!-- SpringDoc OpenAPI - 显式指定版本以兼容 Spring Boot 3.5.x -->
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+            <version>2.8.4</version>
+        </dependency>
+        <dependency>
+            <groupId>com.github.xiaoymin</groupId>
+            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
+            <version>4.5.0</version>
+            <exclusions>
+                <exclusion>
+                    <groupId>org.springdoc</groupId>
+                    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>org.springdoc</groupId>
+                    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>org.springdoc</groupId>
+                    <artifactId>springdoc-openapi-starter-common</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
+
        <dependency>
            <groupId>cn.meowrain</groupId>
            <artifactId>aioj-backend-common-core</artifactId>
--- a/aioj-backend-upms/aioj-backend-upms-biz/pom.xml
+++ b/aioj-backend-upms/aioj-backend-upms-biz/pom.xml
@@ -18,6 +18,32 @@
    </properties>

    <dependencies>
+        <!-- SpringDoc OpenAPI - 显式指定版本以兼容 Spring Boot 3.5.x -->
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+            <version>2.8.4</version>
+        </dependency>
+        <dependency>
+            <groupId>com.github.xiaoymin</groupId>
+            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
+            <version>4.5.0</version>
+            <exclusions>
+                <exclusion>
+                    <groupId>org.springdoc</groupId>
+                    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>org.springdoc</groupId>
+                    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>org.springdoc</groupId>
+                    <artifactId>springdoc-openapi-starter-common</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
+
        <dependency>
            <groupId>cn.meowrain</groupId>
            <artifactId>aioj-backend-common-mybatis</artifactId>
--- a/aioj-backend-user-service/pom.xml
+++ b/aioj-backend-user-service/pom.xml
@@ -18,6 +18,32 @@
    </properties>

    <dependencies>
+        <!-- SpringDoc OpenAPI - 显式指定版本以兼容 Spring Boot 3.5.x -->
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+            <version>2.8.4</version>
+        </dependency>
+        <dependency>
+            <groupId>com.github.xiaoymin</groupId>
+            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
+            <version>4.5.0</version>
+            <exclusions>
+                <exclusion>
+                    <groupId>org.springdoc</groupId>
+                    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>org.springdoc</groupId>
+                    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
+                </exclusion>
+                <exclusion>
+                    <groupId>org.springdoc</groupId>
+                    <artifactId>springdoc-openapi-starter-common</artifactId>
+                </exclusion>
+            </exclusions>
+        </dependency>
+
        <dependency>
            <groupId>cn.meowrain</groupId>
            <artifactId>aioj-backend-common-core</artifactId>
--- a/aioj-backend-user-service/src/main/resources/application.yml
+++ b/aioj-backend-user-service/src/main/resources/application.yml
@@ -20,7 +20,7 @@ springdoc:
    operations-sorter: alpha
  group-configs:
    - group: 'default'
-      paths-to-match: '/**'
+      paths-to-match: '/api/**'
      packages-to-scan: cn.meowrain.aioj.backend.userservice.controller
 knife4j:
  basic:
--- a/pom.xml
+++ b/pom.xml
@@ -24,6 +24,7 @@
        <module>aioj-backend-ai-service</module>
        <module>aioj-backend-auth</module>
        <module>aioj-backend-upms</module>
+        <module>aioj-backend-common/aioj-backend-common-swagger</module>
    </modules>
    <properties>
        <maven.compiler.source>17</maven.compiler.source>
Author	SHA1	Message	Date
meowrain	fc72acf490	feat: 更新配置文件和代码，优化Swagger文档和负载均衡支持	2026-01-08 01:15:56 +08:00
meowrain	05aeef2f79	fix: 网关聚合文档实现	2026-01-08 00:50:32 +08:00
meowrain	9a20a52afb	fix: 放行文档	2026-01-08 00:50:12 +08:00
meowrain	4a4a010f83	feat: 添加swagger公共模块并重构API文档依赖 - 新增 aioj-backend-common-swagger 模块用于统一管理API文档相关依赖 - 从 BOM 中移除 knife4j 依赖，改为按需引入到各服务模块 - 更新 auth、gateway、user-service、upms 等服务的 pom.xml 配置 - 显式指定 springdoc-openapi 版本以兼容 Spring Boot 3.5.x - 添加依赖排除以避免版本冲突 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>	2026-01-08 00:48:37 +08:00