swagger ui 에서 json 이쁘게 출력하기 (springfox 2.9.2 -> 3.0.0)

 

 

 

🎈 현재 swagger response 표시 방법, 문제점 (@ApiResponse)

🎈 @ApiModelProperty 사용법과 단점

🎈 @ApiResponse 를 사용해서 json response 이쁘게 만드는 방법 2가지

🎈 springfox 2.9.2 -> 3.0.0 업그레이드

🎈 추가 내용 (Springfox 와 springdoc)

 

 

 

현재 springboot 2.5.5, swagger 는 springfox 2.9.2 버전을 사용하고 있습니다.

 

http://localhost:8080/swagger-ui.html 로 swagger ui 에 접속하면 각 api 마다 아래와 같이 response가 보입니다.

 

 

 

 

🎈 현재 swagger response 표시 방법, 문제점 (@ApiResponse)

 

이 response를 작성하기 위해 현재 프로젝트에서는 @ApiResponse 를 사용하고 있습니다.

 

하지만 swagger ui 에 접속해서 보니 줄 앞에 스페이스가 안먹히더라구요

 

 

 

 

🎈 @ApiModelProperty 사용법과 단점

 

보통은 @ApiModelProperty 를 사용하는 것 같은데

* 리턴타입에 List<UserInfoDto> 라고 객체를 명확히 작성해야함.

 

몇가지 단점이 있습니다.

 

1. 순서

저희가 class에 작성한 순서가 아니라 알파벳 오름차순으로 나옵니다. 그래서 위 이미지와 같이 data 가 먼저 나왔고, age 가 먼저 나왔습니다.

 

2. List 여도 하나밖에 볼 수 없음

이것을 보여드리기 위해 List<UserInfoDto> 로 만든것입니다.

변수에 @ApiModelProperty 를 직접 설정했기 때문에 예제를 하나밖에 볼 수 없습니다.

자칫 대충 슥 보고 지나가면 '아 이 api 는 단건 응답인가보다~' 하고 넘어갈 수도 있다고 생각합니다. (인간을 100% 신뢰하지 않음)

 

 

 

 

 

여기에 추가로 저희 프로젝트 자체적으로 가지고 있는 에로사항도 있었습니다.

 

1. 앞서 말했듯 저희는 @ApiModelProperty 가 아닌 @ApiResponse 를 사용했습니다. @ApiModelProperty 로 바꾸려면 응답 객체의 각 변수에 일일히 한땀한땀 추가해줘야 합니다.

 

2. 저희는 리턴 타입을 ResponseDto<UserInfoDto> 가 아닌   ResponseDto<Object> 로 작성하여 최상위 클래스인 Object를 사용하였습니다. @ApiModelProperty 로 바꾸려면 명확한 리턴 객체로 한땀한땀 수정해야합니다.

 

3. api 가 수백개 입니다..^^

 

 

 

🎈 @ApiResponse 를 사용해서 json response 이쁘게 만드는 방법 2가지

 

그래서 현재의 코드를 최대한 살리는, 수정 요소를 최소한으로 할 수 있는 방향으로 json을 이쁘게 만들기위한 2가지를 알아냈습니다.

 

1. 스페이스 대신 &nbsp; (non-breaking space) 삽입

스페이스바 하나당 &nbsp; 하나 입니다.

(이거 맞아..?)

예.. 잘 나오긴 합니다만.. 본능적으로 이건 아니다 라는 결론을 내렸습니다.

 

 

2. @ApiResponse 의 examples 를 사용하는 것입니다.

호기롭게 수정하고 http://localhost:8080/swagger-ui.html 에 접속했는데 설정한 MESSAGE 가 보이지 않았습니다. 왜지?

https://github.com/springfox/springfox/issues/3037

@ExampleProperty/value is getting ignored · Issue #3037 · springfox/springfox

examples = @Example({@ExampleProperty...) 가 먹히지 않는건 springfox 2.9.2 의 문제랍니다..

 

 

 

🎈 springfox 2.9.2 -> 3.0.0 업그레이드

 

그래서 3.0.0 으로 바꾸면 되겠지 하고

implementation "io.springfox:springfox-swagger2:2.9.2"
implementation "io.springfox:springfox-swagger-ui:2.9.2"

에서

implementation "io.springfox:springfox-swagger2:3.0.0"
implementation "io.springfox:springfox-swagger-ui: 3.0.0"

으로 숫자만 바꿨습니다.

그랬더니 이번엔 http://localhost:8080/swagger-ui/index.html 에 접속이 안되었습니다.

왜지?

 

Springfox 3.0.0에서는 springfox-boot-starter라는 새로운 스타터 의존성이 도입되었다고 합니다. 이 스타터는 Swagger UI를 포함한 모든 필요한 의존성을 자동으로 가져옵니다.

 

그래서

implementation "io.springfox:springfox-swagger2:3.0.0"
implementation "io.springfox:springfox-swagger-ui: 3.0.0"
이 아닌

implementation "io.springfox:springfox-boot-starter:3.0.0"

을 추가하니 정상적으로 접속됐습니다.

성공~!!!!

 

 

 

 

🎈 추가 내용 (Springfox 와 springdoc)

 

대표적인 Swagger 관련 라이브러리 두가지가 있습니다.
Springfox 와 springdoc
Springfox 는 3.0.0 을 마지막으로 더 이상 업데이트 되지 않습니다.
Springfox 프로젝트는 업데이트가 중단되었으며, Springdoc-openapi 프로젝트로 이관되었습니다.

 

접속 url
Springfox 2.9.2 : http://localhost:8080/swagger-ui.html
Springfox 3.0.0 : http://localhost:8080/swagger-ui/index.html
springdoc :          http://localhost:8080/swagger-ui/index.html

 

그럼 최신거인 springdoc 쓰면 되지 않느냐 고 할 수 있지만 라이브러리만 바꾼다고 되는 것이 아닙니다.

기존 springfox 에서 controller 에 쓰고 있던 @ApiOperation, @ApiImplicitParams 등의 어노테이션을

Springdoc 용 @Operation, @Parameter 등으로 바꿔줘야 합니다.