Spring boot에서 API Docs를 만들기 위해 많이 사용하는 Swagger를 이용해서 이런저런 시도를 해보고 있다. 구글링으로 나온 자료들을 따라해보고 막히면 삽질도 해보고 하던 도중 개념을 확실하게 짚어야 할 부분이 있어서 기록한다.
나와 같은 경우에는 Springfox Swagger를 사용하다가, 지원되지 않는 부분(그룹핑, 정렬)에 한계를 느껴 현재 Springdoc으로 넘어온 상태다. 막히는 부분을 검색할 때도 Springdoc에 대한 정보가 상대적으로 더 많게 느껴졌다.

Swagger

2011년에 처음 나왔다.
RESTFul 웹 서비스를 만들 때 API 문서를 자동으로 만들어주고, 직접 테스트할 수 있는 UI를 제공한다.
공식 홈페이지
Swagger UI

Springfox Swagger

Spring framework를 사용하는 프로젝트에서 Swagger를 이용할 수 있게 도와주는 라이브러리

mvnrepository 기준 2015년에 처음 나와 2020년 7월에 3.0.0 버전을 마지막으로 업데이트 되고 있지 않다.
2018년까지 많은 사용자가 사용한 것으로 보이나 2018년 6월을 기점으로 업데이트가 2년 간 중단되었다.

Spingdoc

Springfox Swagger와 마찬가지로 Swagger를 이용할 수 있게 도와주는 라이브러리
Springfox가 업데이트를 중단한 사이(2019년 7월)에 처음 나왔다.

mvnrepository 기준 비교적 최근인 2022년 5월까지 업데이트되었다.

무엇이 다른가?

• Springfox가 2년 간 업데이트 하지 않는 동안 Springdoc은 webflux라는 논 블록킹 비동기 방식의 웹 개발을 지원하도록 개발되었다.
• Springdoc이 후발주자라서 그런지(?) Springfox를 더 발전시킨 모습이며, 더 사용하기 쉽다고 한다.

여기서부터는 내가 직접 사용하고 느꼈던 차이점이다.
(Springfox를 얕게 사용하고 Springdoc으로 넘어간 나는 어느 쪽이 훨씬 낫다!고 체감한 건 사실 많이 없다.)

• @Tag 어노테이션의 사용 범위가 다른 것 같았다.
  Springdoc에서는 클래스단위로 @Tag 어노테이션을 사용해서 그룹핑할 수 있는데, Springfox에서는 클래스뿐만 아니라 메소드 단위로도 같은 어노테이션을 넣어줘야해서 별 거 아니지만 중복되는 코드 양이 많았다.
• Springfox에서는 api 간 정렬이 되지 않는다.
  Springdoc에서는 properties 파일을 이용해서 그룹 간, api 간 정렬이 가능하다. (abc순, method순)