Skip to content

feat: DisableSwaggerSecurity 어노테이션으로 Swagger 내 로그인과 토큰 갱신 API 보안 설정을 비활성화하는 기능 추가 #87

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
move-hoon merged 15 commits into from
Aug 9, 2025
Merged

feat: DisableSwaggerSecurity 어노테이션으로 Swagger 내 로그인과 토큰 갱신 API 보안 설정을 비활성화하는 기능 추가 #87

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
0f70fbf
[BOOK-90] fix: gateway - 화이트리스트를 제외하고, 모든 경로에 인증된 사용자만 접근 가능하도록 수정
move-hoon Aug 8, 2025
36067d8
[BOOK-90] feat: global-utils - Swagger 보안을 비활성화하는 어노테이션 추가
move-hoon Aug 8, 2025
8fc6fa6
[BOOK-90] feat: apis - Swagger 보안 설정을 비활성화하는 OperationCustomizer 추가
move-hoon Aug 8, 2025
6aace86
[BOOK-90] feat: apis - 소셜 로그인 및 토큰 갱신 API에 Swagger 보안 비활성화 어노테이션 추가
move-hoon Aug 8, 2025
9f365f9
[BOOK-90] chore: apis - Book 관련 유틸 클래스 book 패키지로 이동
move-hoon Aug 9, 2025
2bfddf5
[BOOK-90] refactor: apis, global-utils - 코드레빗 리뷰 반영
move-hoon Aug 9, 2025
40c0bbf
[BOOK-90] feat: apis, global-utils - ApplicationService 커스텀 어노테이션 생성 …
move-hoon Aug 9, 2025
90716b2
[BOOK-90] chore: apis - DTO에 스키마 명세 추가
move-hoon Aug 9, 2025
cb2340b
[BOOK-90] chore: apis - 가독성을 위한 반환 방식 리팩토링
move-hoon Aug 9, 2025
76851b7
[BOOK-90] refactor: apis, domain - 애플 리프레쉬 토큰 관련 DTO 내부 로직 변경
move-hoon Aug 9, 2025
ce96fb3
[BOOK-90] fix: apis - item 내부에 있는 link를 전달하도록 수정
move-hoon Aug 9, 2025
558d48b
[BOOK-90] chore: apis - 최소 개수 명세 추가
move-hoon Aug 9, 2025
7c3977e
[BOOK-90] refactor: apis - 애플 refreshToken이 null이나 빈문자열로 올 경우 기존 init…
move-hoon Aug 9, 2025
dc46056
[BOOK-90] refactor: apis - 프로퍼티 위의 @Schema만 @field:Schema로 변경
move-hoon Aug 9, 2025
a6516db
[BOOK-90] chore: apis - categories 프로퍼티의 명세 변경
move-hoon Aug 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions apis/src/main/kotlin/org/yapp/apis/auth/controller/AuthControllerApi.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,14 @@ import org.springframework.web.bind.annotation.RequestBody
import org.yapp.apis.auth.dto.request.SocialLoginRequest
import org.yapp.apis.auth.dto.request.TokenRefreshRequest
import org.yapp.apis.auth.dto.response.AuthResponse
import org.yapp.globalutils.annotation.DisableSwaggerSecurity
Copy link

@coderabbitai coderabbitai bot Aug 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

인터페이스에 @DisableSwaggerSecurity 부착은 의도에 부합하지만, 현 Customizer 로직으로는 미감지 위험

  • 본 파일처럼 “인터페이스 메서드”에 어노테이션을 부착하는 패턴은 좋습니다.
  • 다만 현재 SwaggerConfig.securityOperationCustomizer()가 handlerMethod.getMethodAnnotation(...)로만 검사하면, 구현 클래스의 메서드에 어노테이션이 없을 때(=인터페이스에만 있을 때) 감지가 누락될 수 있습니다.
  • 제안한 대로 AnnotatedElementUtils.findMergedAnnotation 기반 + 인터페이스 메서드 탐색으로 보강하면 안정적으로 동작합니다. 관련 수정 제안은 SwaggerConfig.kt 코멘트를 참고하세요.

빠른 점검:

Also applies to: 25-25, 52-52

🏁 Script executed:

#!/bin/bash
# 인터페이스에만 어노테이션이 달려있는지, 구현체에는 없는지 확인
rg -n "@DisableSwaggerSecurity" -S

Length of output: 240

다음 스크립트를 실행해 SwaggerConfig.kt 내 securityOperationCustomizer 구현이 handlerMethod.getMethodAnnotation만 사용하고 있는지 확인해 주세요:

🏁 Script executed:

#!/bin/bash
# SwaggerConfig 파일 경로 찾기 및 securityOperationCustomizer 내용 확인
file=$(rg -l "class SwaggerConfig" -S)
echo "SwaggerConfig file: $file"
rg -n -A5 -B5 "securityOperationCustomizer" "$file"

Length of output: 784

securityOperationCustomizer 로직 보강 필요: 인터페이스 메서드 어노테이션 감지 누락

현재 SwaggerConfig.kt의 securityOperationCustomizer는 구현 클래스의 메서드에만 붙은 어노테이션을 handlerMethod.getMethodAnnotation(...)로 조회하기 때문에, 인터페이스에만 선언된 @DisableSwaggerSecurity를 놓칠 수 있습니다. 아래 위치를 수정해 주세요.

  • 대상 파일:
    apis/src/main/kotlin/org/yapp/apis/config/SwaggerConfig.kt
  • 메서드:
    fun securityOperationCustomizer (라인 57~63)

현 구현 예시:

val disableSwaggerSecurity: DisableSwaggerSecurity? =
    handlerMethod.getMethodAnnotation(DisableSwaggerSecurity::class.java)

제안된 수정 방법 (인터페이스 메서드까지 탐색):

import org.springframework.core.annotation.AnnotatedElementUtils

val disableSwaggerSecurity: DisableSwaggerSecurity? =
    AnnotatedElementUtils.findMergedAnnotation(
        handlerMethod.method, 
        DisableSwaggerSecurity::class.java
    ) ?: AnnotatedElementUtils.findMergedAnnotation(
        handlerMethod.beanType.getMethod(
            handlerMethod.method.name,
            *handlerMethod.method.parameterTypes
        ),
        DisableSwaggerSecurity::class.java
    )

위와 같이 변경하면 인터페이스에 선언된 @DisableSwaggerSecurity도 안정적으로 감지됩니다.

🤖 Prompt for AI Agents 
In apis/src/main/kotlin/org/yapp/apis/config/SwaggerConfig.kt around lines 57 to
63, the current securityOperationCustomizer method only checks for the
@DisableSwaggerSecurity annotation on the implementation method using
handlerMethod.getMethodAnnotation, which misses annotations declared on
interface methods. To fix this, replace the annotation retrieval with
AnnotatedElementUtils.findMergedAnnotation to first check the implementation
method and if not found, check the corresponding interface method by name and
parameter types. This ensures that @DisableSwaggerSecurity annotations declared
on interface methods are also detected correctly.

import org.yapp.globalutils.exception.ErrorResponse
import java.util.*

@Tag(name = "Authentication", description = "인증 관련 API")
interface AuthControllerApi {

@DisableSwaggerSecurity
@Operation(
summary = "소셜 로그인",
description = "카카오 또는 애플 계정으로 로그인합니다. 사용자가 존재하지 않으면 자동으로 회원가입됩니다."
Expand All @@ -47,6 +49,7 @@ interface AuthControllerApi {
@PostMapping("/signin")
fun signIn(@RequestBody @Valid request: SocialLoginRequest): ResponseEntity<AuthResponse>

@DisableSwaggerSecurity
@Operation(
summary = "토큰 갱신",
description = "리프레시 토큰을 사용하여 액세스 토큰을 갱신합니다. 새로운 액세스 토큰과 리프레시 토큰을 반환합니다."
Expand Down
16 changes: 16 additions & 0 deletions apis/src/main/kotlin/org/yapp/apis/config/SwaggerConfig.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,12 @@ import io.swagger.v3.oas.models.info.Info
import io.swagger.v3.oas.models.security.SecurityRequirement
import io.swagger.v3.oas.models.security.SecurityScheme
import io.swagger.v3.oas.models.servers.Server
import org.springdoc.core.customizers.OperationCustomizer
import org.springframework.boot.context.properties.EnableConfigurationProperties
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.context.annotation.Profile
import org.yapp.globalutils.annotation.DisableSwaggerSecurity

@Configuration
@EnableConfigurationProperties(SwaggerProperties::class)
Expand Down Expand Up @@ -50,4 +52,18 @@ class SwaggerConfig(
)
)
}

@Bean
fun securityOperationCustomizer(): OperationCustomizer {
return OperationCustomizer { operation, handlerMethod ->
val disableSwaggerSecurity: DisableSwaggerSecurity? =
handlerMethod.getMethodAnnotation(DisableSwaggerSecurity::class.java)

if (disableSwaggerSecurity != null) {
operation.security = listOf()
}

operation
}
}
}
3 changes: 0 additions & 3 deletions gateway/src/main/kotlin/org/yapp/gateway/security/SecurityConfig.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,6 @@ class SecurityConfig(
.authorizeHttpRequests {
it.requestMatchers(*WHITELIST_URLS).permitAll()
it.requestMatchers("/api/v1/admin/**").hasRole("ADMIN")
it.requestMatchers("/api/v1/user/**").hasAnyRole("USER", "ADMIN")
it.requestMatchers("/api/v1/auth/**").authenticated()
it.requestMatchers("/api/v1/books/**").authenticated()
it.anyRequest().authenticated()
}

Expand Down
5 changes: 5 additions & 0 deletions global-utils/src/main/kotlin/org/yapp/globalutils/annotation/DisableSwaggerSecurity.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
package org.yapp.globalutils.annotation

@Target(AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class DisableSwaggerSecurity()
Copy link

@coderabbitai coderabbitai bot Aug 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

KDoc와 문서화 어노테이션 추가, Kotlin 스타일 닛픽

  • 사용 의도를 KDoc에 남기고, API 문서 생성 시 노출되도록 @MustBeDocumented를 권장합니다.
  • 빈 생성자 괄호는 불필요하므로 제거를 권장합니다.

적용 예시:

 @Target(AnnotationTarget.FUNCTION)
 @Retention(AnnotationRetention.RUNTIME)
-annotation class DisableSwaggerSecurity()
+@MustBeDocumented
+annotation class DisableSwaggerSecurity

간단한 KDoc도 추가하면 더 좋습니다:

/**
 * Swagger(OpenAPI) 문서에서 해당 Operation의 보안 요구 사항을 제거합니다.
 * - 실제 런타임 보안에는 영향 없음 (문서 전용)
 * - 로그인/토큰 갱신 등 공개 엔드포인트 명시용
 */
🤖 Prompt for AI Agents 
In
global-utils/src/main/kotlin/org/yapp/globalutils/annotation/DisableSwaggerSecurity.kt
around lines 3 to 5, add a KDoc comment above the annotation class explaining
its purpose as removing security requirements from Swagger documentation only,
and annotate the class with @MustBeDocumented to ensure it appears in generated
API docs. Also, remove the unnecessary empty parentheses from the annotation
class declaration to follow Kotlin style conventions.

Copy link
Member

@minwoo1999 minwoo1999 Aug 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

docs 써주면 추후에 도움이 많이 될 것 같아요!

Copy link

@coderabbitai coderabbitai bot Aug 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@minwoo1999 네, 맞습니다! 문서화는 팀원들이 어노테이션의 목적과 사용법을 빠르게 이해하는 데 큰 도움이 됩니다. 특히 @DisableSwaggerSecurity처럼 특정 목적을 가진 커스텀 어노테이션의 경우, KDoc을 통해 명확한 의도를 전달하는 것이 중요합니다.

제안드린 KDoc과 @MustBeDocumented 어노테이션을 추가하시면 IDE에서도 바로 문서를 확인할 수 있어 개발 효율성이 높아질 것입니다. 👍