Swagger. Springfox-Swagger 그리고 Springdoc
요즘 스프링으로 프로젝트를 하면서 이런저런 지식들을 습득하고 있습니다.
예전에 스프링으로 프로젝트하시던 분들이 swagger를 이용해서 API문서를 만들던 것을 보고 swagger라는 것에 대해 듣게 되었었는데요. 다만 개념을 제대로 이해하고 있지 못했었습니다. springfox-swagger라고 적힌 걸 보고 그냥 같은 녀석이라고 생각을 했었는데요. 알고 보니 springfox-swagger와 swagger랑은 다른 녀석이었습니다. 물론 관련은 있지만요.
Swagger
Swagger는 2011년에 처음 릴리즈 되었습니다. Swagger는 RESTful 웹 서비스를 만들 때 API의 문서를 자동으로 만들어 주고, API를 직접 테스트해 볼 수 있는 웹 UI툴을 제공해줍니다.
API Documentation & Design Tools for Teams | Swagger
swagger.io
https://swagger.io/tools/swagger-ui/
REST API Documentation Tool | Swagger UI
swagger.io
데모 https://petstore.swagger.io/#/
Swagger UI
petstore.swagger.io
Springfox Swagger
스프링 프레임워크를 사용하는 프로젝트에서 Swagger를 이용해서 API문서를 쉽게 쓸 수 있도록 도와주는 라이브러리로 Springfox가 있습니다.
https://springfox.github.io/springfox/docs/current/
Springfox Reference Documentation
The Springfox suite of java libraries are all about automating the generation of machine and human readable specifications for JSON APIs written using the spring family of projects. Springfox works by examining an application, once, at runtime to infer API
springfox.github.io
아직 정확한 히스토리까지는 잘 모르겠지만 maven repository를 보면 2015년에 본격 나온 게 아닐까 싶습니다.
https://mvnrepository.com/artifact/io.springfox
Maven Repository: io.springfox
JSON API documentation for spring based applications Last Release on Jun 22, 2020
mvnrepository.com
찾아보니 이전에는 Swagger SpringMVC라는 이름이었던 거 같습니다. 2012년~2015년까지 Swagger SpringMVC 였다가 2015년부터 Springfox Swagger로 바뀐 거 같네요.
https://mvnrepository.com/artifact/com.mangofactory/swagger-springmvc
Maven Repository: com.mangofactory » swagger-springmvc
This project integrates swagger with the Spring Web MVC framework VersionRepositoryUsagesDate1.0.x1.0.2Central14Mar, 20151.0.1Central1Mar, 20151.0.0Central1Mar, 20150.9.x0.9.5Central8Jan, 20150.9.4Central2Dec, 20140.9.3Central1Dec, 20140.9.2Central 0 Dec,
mvnrepository.com
2018년까지 Springfox Swagger는 많은 사용자들이 사용해 왔던 것으로 보입니다. 그런데 2018년 6월을 마지막으로 업데이트가 중단되었습니다. (라고 적었지만 2년 만에 다시 업데이트가 되었습니다. 관련 내용은 마지막에 다룹니다.)
Springdoc
Springfox Swagger가 업데이트를 중단한 사이 Springdoc이 나타납니다. Springdoc도 Springfox와 마찬가지로 스프링으로 개발하는 프로젝트의 swagger문서를 쉽게 작성할 수 있도록 도와주는 라이브러리입니다.
https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui
Maven Repository: org.springdoc » springdoc-openapi-ui
mvnrepository.com
를 보면 2019년 7월부터 시작된 프로젝트로 보입니다. 꾸준히 업데이트되어 왔고 현재 1.4.1까지 나왔습니다.
후발주자라 그런지 Springfox보다 좀 더 쉽게 사용할 수 있도록 만든 느낌이었습니다. 관련해서는 다음에 좀 더 다루겠습니다. 최근 Spring에서는 점점 webflux라는 논 블록킹 비동기 방식의 웹 개발을 밀고 있는데요. Springfox가 이와 관련해서 업데이트를 하고 있지 않는 동안 Springdoc에서 지원을 하도록 개발하였습니다.
참고로 Springfox에서 비공식 버전인 3.0.0-SNAPSHOT에서 webflux를 일부 지원하고 있었습니다. 그런데 얼마 전까지 쓰고 있었는데 이게 maven으로 못 불러와지더군요. 아마 지워진 거 같습니다.
Springfox의 부활?
이 글을 작성하려고 했을 때 사실 Springfox는 2018년부터 업데이트가 안되고 있었고 2019년부터 Springdoc이 등장했기 때문에 대세는 자연스럽게 Springdoc이 되지 않을까 했습니다.
그런데 2년 동안 침묵하고 있던 Springfox가 갑자기 신버전인 2.10.0을 내놓았습니다.
저와 제 주변 사람들 중 많은 사람들이 최근 Springdoc으로 넘어간 상태인데요. 그 점을 의식한 건지 갑자기 신버전이 나왔습니다. 간단히 샘플 프로젝트를 만들어 보니 webflux도 지원하고 있고요.
Springdoc으로 넘어가자마자 Springfox의 2년 만의 업데이트라니 고민이 됩니다. 비슷한 역할을 하는 두 개의 프로젝트가 두 개가 되는 것인데요. 최후의 승자는 누가 될까요?