261012_01_ENH: RequestUserContext Swagger 입력 숨김 처리

This commit is contained in:
2026-10-12 17:17:09 +09:00
parent 65e31079ac
commit 7cd170fe6e
7 changed files with 16 additions and 1 deletions

View File

@@ -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. - 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. - 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. - 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. - 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. - 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`. - The external API client returns response bodies as documented, while bypass responses preserve raw bytes and target `Content-Type`.

View File

@@ -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. - 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. - 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. - 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. - 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. - 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`. - The external API client returns response bodies as documented, while bypass responses preserve raw bytes and target `Content-Type`.

View File

@@ -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. - 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. - 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. - 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. - Do not modify KriCommon or another consumer repository unless it is explicitly included in the approved task scope.
### Required Shared References ### Required Shared References

View File

@@ -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. - 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. - 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. - 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. - Do not modify KriCommon or another consumer repository unless it is explicitly included in the approved task scope.
### Required Shared References ### Required Shared References

View File

@@ -99,6 +99,8 @@ import com.kri.common.feature.web.RequestUserContext;
컨트롤러 파라미터로 선언하면 현재 인증 사용자와 client IP를 받을 수 있습니다. `JwtService` Bean이 있을 때 `RequestUserContextArgumentResolver`가 자동 등록됩니다. 컨트롤러 파라미터로 선언하면 현재 인증 사용자와 client IP를 받을 수 있습니다. `JwtService` Bean이 있을 때 `RequestUserContextArgumentResolver`가 자동 등록됩니다.
Swagger 자동 구성이 활성화되면 `RequestUserContext`는 요청 입력 문서에서 제외됩니다. `authenticated`, `clientIp`, `userRole` 등의 입력 항목은 표시되지 않으며, 실제 요청의 인증 정보와 IP 주입 동작은 유지됩니다.
```java ```java
@GetMapping("/me") @GetMapping("/me")
public Object me(RequestUserContext user) { 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 - API Key admin API가 활성화되면 내부 admin endpoint package도 scan
- Swagger UI/API docs 접근 IP 제한 - Swagger UI/API docs 접근 IP 제한
- `CodeEnum` 구현 enum의 schema/parameter 설명 보강 - `CodeEnum` 구현 enum의 schema/parameter 설명 보강
- 서버가 주입하는 `RequestUserContext`를 요청 입력 문서에서 제외
### `kri.web` ### `kri.web`

View File

@@ -4,7 +4,7 @@ plugins {
} }
// 버전 변경은 여기서 // 버전 변경은 여기서
def commonVer = "beta.1.6.8" def commonVer = "beta.1.6.9"
group = 'com.kri.common' group = 'com.kri.common'
version = commonVer version = commonVer

View File

@@ -1,6 +1,7 @@
package com.kri.common.autoconfigure.swagger; package com.kri.common.autoconfigure.swagger;
import com.kri.common.autoconfigure.auth.apikey.ApiKeyProperties; 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.CodeEnumOpenApiCustomizer;
import com.kri.common.runtime.swagger.CodeEnumModelConverter; import com.kri.common.runtime.swagger.CodeEnumModelConverter;
import com.kri.common.runtime.swagger.CodeEnumSwaggerSupport; 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.parameters.Parameter;
import io.swagger.v3.oas.models.security.SecurityRequirement; import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme; import io.swagger.v3.oas.models.security.SecurityScheme;
import jakarta.annotation.PostConstruct;
import java.util.LinkedHashSet; import java.util.LinkedHashSet;
import java.util.Set; import java.util.Set;
import lombok.RequiredArgsConstructor; import lombok.RequiredArgsConstructor;
@@ -21,6 +23,7 @@ import org.springdoc.core.customizers.GlobalOpenApiCustomizer;
import org.springdoc.core.customizers.ParameterCustomizer; import org.springdoc.core.customizers.ParameterCustomizer;
import org.springdoc.core.customizers.PropertyCustomizer; import org.springdoc.core.customizers.PropertyCustomizer;
import org.springdoc.core.models.GroupedOpenApi; import org.springdoc.core.models.GroupedOpenApi;
import org.springdoc.core.utils.SpringDocUtils;
import org.springframework.boot.autoconfigure.AutoConfiguration; import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass; import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean; import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
@@ -42,6 +45,11 @@ public class KriSwaggerAutoConfiguration {
private final KriSwaggerProperties properties; private final KriSwaggerProperties properties;
private final ApiKeyProperties apiKeyProperties; // apikey.header-name 읽기용 private final ApiKeyProperties apiKeyProperties; // apikey.header-name 읽기용
@PostConstruct
void hideRequestUserContext() {
SpringDocUtils.getConfig().addRequestWrapperToIgnore(RequestUserContext.class);
}
@Bean @Bean
@ConditionalOnMissingBean @ConditionalOnMissingBean
public OpenAPI kriOpenAPI() { public OpenAPI kriOpenAPI() {