Swagger 3 (springdoc-openapi-ui) 에서 @AuthenticationPrincipal 파라미터 무시 전역 설정

서론

현재 진행 중인 프로젝트의 공식 문서를 Swagger로 정하고 작업을 진행하고 있는데,

앱 개발자와 협업을 하며 Swagger 확인 도중 @AuthenticationPrincipal를 이용하여 회원을 파라미터로 받는 엔드포인트에 다음과 같이 지속적으로 빈 괄호를 넘겨줘야 정상 작동하는 상황이 발생하였다.

빈 값을 전달하면 다음과 같이 에러가 발생하였다.

본론 

위 내용을 해결하기 위해 @AuthenticationPrincipal이 들어가는 EndPoint에

@Parameter(hidden = true)를 설정을 하여 문제는 해결이 되었으나 저 메서드가 들어가는 모든 엔드포인트에 설정하기는

작업이 번거로워 전역적인 설정이 없는지 찾아보았다.

@Parameter(hidden = true)를 처리하여 아래와 같이 해당 엔드포인트에서 Parameter를 없앨 수 있었다.

viewer Parameter가 없어진 모습

 

전역적인 설정을 위해 검색을 해보니

springfox-swagger-ui , springfox-swagger2 라이브러리를 기반으로 한 설정들만 찾을 수 있었다.

GPT-3.5에서 제공한 springdoc-openapi, springfox-swagger-ui의 차이점

 

 

내가 사용하고있는 Swagger3 라이브러리는 springdoc-openapi-ui였기 때문에 해당 설정들을 열심히 찾아보던 중, 

내가 사용하는 라이브러리의 깃헙의 이슈에서 해당 내용을 찾을 수 있었다.

 

@AuthenticationPrincipal is not ignored and overwrites @RequestBody parameters · Issue #198 · springdoc/springdoc-openapi (github.com)

@AuthenticationPrincipal is not ignored and overwrites @RequestBody parameters · Issue #198 · springdoc/springdoc-openapi

내용의 요약은 나와 같은 문제로

- @AuthenticationPrincipal의 객체가 Swagger에서 안 보이게 하고 싶은 사람이 Issue를 올렸고 

- 공식 답변으로 내가 처리했던 @Parameter(hidden = true)을 하라고 답변을 주었다.

- Security에서 동작을 처리한 모듈이 추가되었다는 댓글이 달렸고, springdoc-openapi-security 의존성을 추가하면 된다 라는 내용이었다.

 

build.gradle 설정

19년도 글이였기 때문에, 버전 호환이 안될 수 있을 것 같아서 자동완성으로 버전을 확인을 해보다가 프로젝트에서 사용되고있는 spring-openapi-ui 버전이 1.6.13 이였기 때문에 같은 버전으로 해당 security 버전을 추가해 보았다.

 

 

추가 후 @Parameter(hidden = true)를 제거하고, 

Swagger 페이지에 들어가 @AuthenticationPrincipal이 들어간 endPoint들을 확인해 보았다.

@AuthenticationPrincipal이 들어간 상세 조회 API

Swagger에서 해당 파라미터가 무시되고있다.

다음과 같이 적용이 된 것을 확인할 수 있다.

 

결론

간단하게 문제를 해결했음에도 전역적으로 문제를 해결하기 위해 찾아보며

내가 왜 Swagger3을 사용하기 위해 springdoc-openapi-ui를 사용했었는지 배울 수 있었던 것 같다.

간단한 내용이지만 글을 남긴 건 한국어로 정리가 되어있는 글이 없어 정리를 해놓고 싶었기 때문이었다.

추가된 springdoc-openapi-security 라이브러리를 조금 더 분석을 해보아야겠다.