From 7cd170fe6ece94ce37c14f3deeeb05937641e4c1 Mon Sep 17 00:00:00 2001 From: kric_jspark Date: Mon, 12 Oct 2026 17:17:09 +0900 Subject: [PATCH] =?UTF-8?q?261012=5F01=5FENH:=20RequestUserContext=20Swagg?= =?UTF-8?q?er=20=EC=9E=85=EB=A0=A5=20=EC=88=A8=EA=B9=80=20=EC=B2=98?= =?UTF-8?q?=EB=A6=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../references/kri-common/platform-capabilities.md | 1 + .agent/consumer-references/platform-capabilities.md | 1 + .agent/consumer.md | 1 + AGENTS.md | 1 + README.md | 3 +++ build.gradle | 2 +- .../swagger/KriSwaggerAutoConfiguration.java | 8 ++++++++ 7 files changed, 16 insertions(+), 1 deletion(-) diff --git a/.agent-harness/references/kri-common/platform-capabilities.md b/.agent-harness/references/kri-common/platform-capabilities.md index 510ecac..175b115 100644 --- a/.agent-harness/references/kri-common/platform-capabilities.md +++ b/.agent-harness/references/kri-common/platform-capabilities.md @@ -20,6 +20,7 @@ Source: .agent/consumer-references/platform-capabilities.md - JWT and API-key authentication integrate with Spring Security. API-key JPA preload requires Spring Data JPA; a consumer-provided claims provider can be used without JPA. - Common Web may register error handling, tracing/MDC, request-user resolution, enum conversion, and CORS behavior. Check for overlap before defining consumer-local equivalents. - Swagger support requires springdoc and defines the shared Bearer/API-key schemes and grouped paths. +- When Swagger auto-configuration is active (`kri.swagger.enabled=true`, default), `RequestUserContext` controller arguments are ignored as request inputs globally, including their `authenticated`, `clientIp`, and `userRole` properties. Runtime argument resolution is unchanged. - Redis and scheduling are opt-in through their `kri.*.enabled` settings and matching runtime dependencies. - HTTP bypass targets are server-configured. Never accept an arbitrary full target URL from a frontend; retain allowed-path checks and do not forward hop-by-hop headers. - The external API client returns response bodies as documented, while bypass responses preserve raw bytes and target `Content-Type`. diff --git a/.agent/consumer-references/platform-capabilities.md b/.agent/consumer-references/platform-capabilities.md index 714f02b..e4895c9 100644 --- a/.agent/consumer-references/platform-capabilities.md +++ b/.agent/consumer-references/platform-capabilities.md @@ -14,6 +14,7 @@ - JWT and API-key authentication integrate with Spring Security. API-key JPA preload requires Spring Data JPA; a consumer-provided claims provider can be used without JPA. - Common Web may register error handling, tracing/MDC, request-user resolution, enum conversion, and CORS behavior. Check for overlap before defining consumer-local equivalents. - Swagger support requires springdoc and defines the shared Bearer/API-key schemes and grouped paths. +- When Swagger auto-configuration is active (`kri.swagger.enabled=true`, default), `RequestUserContext` controller arguments are ignored as request inputs globally, including their `authenticated`, `clientIp`, and `userRole` properties. Runtime argument resolution is unchanged. - Redis and scheduling are opt-in through their `kri.*.enabled` settings and matching runtime dependencies. - HTTP bypass targets are server-configured. Never accept an arbitrary full target URL from a frontend; retain allowed-path checks and do not forward hop-by-hop headers. - The external API client returns response bodies as documented, while bypass responses preserve raw bytes and target `Content-Type`. diff --git a/.agent/consumer.md b/.agent/consumer.md index 94e8124..1811aab 100644 --- a/.agent/consumer.md +++ b/.agent/consumer.md @@ -5,6 +5,7 @@ - Prefer a shared feature or approved extension point over duplicating authentication, HTTP, error, enum, Excel, Redis, JSON, date/time, JPA, crypto, or utility behavior locally. - For HTTP/2 header safety and original upstream error propagation, use the shared HTTP/bypass features documented in the routed platform-capabilities reference instead of implementing consumer-local header filters and raw-response exception handlers. - Response customizers may call `requireSuccess()`; its upstream exception propagates unchanged. Response charset parsing ignores charset-like text inside other quoted header parameters. +- When Swagger auto-configuration is active, `RequestUserContext` controller arguments are excluded from request input documentation; server-side authentication and client IP injection remain unchanged. - Do not modify KriCommon or another consumer repository unless it is explicitly included in the approved task scope. ### Required Shared References diff --git a/AGENTS.md b/AGENTS.md index d2aa3a3..98f89c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -234,6 +234,7 @@ When implementation is complete, report in Korean: - Prefer a shared feature or approved extension point over duplicating authentication, HTTP, error, enum, Excel, Redis, JSON, date/time, JPA, crypto, or utility behavior locally. - For HTTP/2 header safety and original upstream error propagation, use the shared HTTP/bypass features documented in the routed platform-capabilities reference instead of implementing consumer-local header filters and raw-response exception handlers. - Response customizers may call `requireSuccess()`; its upstream exception propagates unchanged. Response charset parsing ignores charset-like text inside other quoted header parameters. +- When Swagger auto-configuration is active, `RequestUserContext` controller arguments are excluded from request input documentation; server-side authentication and client IP injection remain unchanged. - Do not modify KriCommon or another consumer repository unless it is explicitly included in the approved task scope. ### Required Shared References diff --git a/README.md b/README.md index 14e28e9..49e60e7 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,8 @@ import com.kri.common.feature.web.RequestUserContext; 컨트롤러 파라미터로 선언하면 현재 인증 사용자와 client IP를 받을 수 있습니다. `JwtService` Bean이 있을 때 `RequestUserContextArgumentResolver`가 자동 등록됩니다. +Swagger 자동 구성이 활성화되면 `RequestUserContext`는 요청 입력 문서에서 제외됩니다. `authenticated`, `clientIp`, `userRole` 등의 입력 항목은 표시되지 않으며, 실제 요청의 인증 정보와 IP 주입 동작은 유지됩니다. + ```java @GetMapping("/me") public Object me(RequestUserContext user) { @@ -812,6 +814,7 @@ other paths require both an allowed client IP and authentication. Exact IPs, CID - API Key admin API가 활성화되면 내부 admin endpoint package도 scan - Swagger UI/API docs 접근 IP 제한 - `CodeEnum` 구현 enum의 schema/parameter 설명 보강 +- 서버가 주입하는 `RequestUserContext`를 요청 입력 문서에서 제외 ### `kri.web` diff --git a/build.gradle b/build.gradle index 08b8421..fe71fed 100644 --- a/build.gradle +++ b/build.gradle @@ -4,7 +4,7 @@ plugins { } // 버전 변경은 여기서 -def commonVer = "beta.1.6.8" +def commonVer = "beta.1.6.9" group = 'com.kri.common' version = commonVer diff --git a/src/main/java/com/kri/common/autoconfigure/swagger/KriSwaggerAutoConfiguration.java b/src/main/java/com/kri/common/autoconfigure/swagger/KriSwaggerAutoConfiguration.java index f58573e..b178436 100644 --- a/src/main/java/com/kri/common/autoconfigure/swagger/KriSwaggerAutoConfiguration.java +++ b/src/main/java/com/kri/common/autoconfigure/swagger/KriSwaggerAutoConfiguration.java @@ -1,6 +1,7 @@ package com.kri.common.autoconfigure.swagger; import com.kri.common.autoconfigure.auth.apikey.ApiKeyProperties; +import com.kri.common.feature.web.RequestUserContext; import com.kri.common.runtime.swagger.CodeEnumOpenApiCustomizer; import com.kri.common.runtime.swagger.CodeEnumModelConverter; import com.kri.common.runtime.swagger.CodeEnumSwaggerSupport; @@ -14,6 +15,7 @@ import io.swagger.v3.oas.models.media.Schema; 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 jakarta.annotation.PostConstruct; import java.util.LinkedHashSet; import java.util.Set; import lombok.RequiredArgsConstructor; @@ -21,6 +23,7 @@ import org.springdoc.core.customizers.GlobalOpenApiCustomizer; import org.springdoc.core.customizers.ParameterCustomizer; import org.springdoc.core.customizers.PropertyCustomizer; import org.springdoc.core.models.GroupedOpenApi; +import org.springdoc.core.utils.SpringDocUtils; import org.springframework.boot.autoconfigure.AutoConfiguration; import org.springframework.boot.autoconfigure.condition.ConditionalOnClass; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; @@ -42,6 +45,11 @@ public class KriSwaggerAutoConfiguration { private final KriSwaggerProperties properties; private final ApiKeyProperties apiKeyProperties; // apikey.header-name 읽기용 + @PostConstruct + void hideRequestUserContext() { + SpringDocUtils.getConfig().addRequestWrapperToIgnore(RequestUserContext.class); + } + @Bean @ConditionalOnMissingBean public OpenAPI kriOpenAPI() {