Swagger란?#
Swagger는 OAS(OpenAPI Specification)를 위한 프레임워크로, API들이 가지고 있는 스펙을 명세하고 관리할 수 있는 프로젝트입니다. Swagger를 통해 REST API 서비스를 설계, 빌드, 문서화할 수 있습니다.
Swagger Tools#
Swagger는 다음과 같은 주요 도구들을 제공합니다
- Swagger UI: Swagger API 명세서를 HTML 형식으로 시각화하여 확인할 수 있도록 해주는 도구
- Swagger Codegen: Swagger에 정의된 스펙에 따라 클라이언트 및 서버 코드를 자동으로 생성해주는 CLI 툴
- Swagger Editor: Swagger 표준에 따른 API 설계서 및 명세서를 작성하기 위한 에디터
Springfox vs Springdoc#
Springfox Swagger는 Spring 또는 Spring Boot를 사용하는 프로젝트에서 Swagger를 이용해 API 문서를 쉽게 작성할 수 있도록 도와주는 라이브러리입니다.
Springfox가 업데이트를 중단하는 시점에 Springdoc이 등장했으며, 활발한 업데이트가 이루어지면서 급부상하게 되었습니다. Springdoc 역시 Swagger 문서 작성을 지원하는 라이브러리로, 현재는 Springfox보다 더 권장되는 선택입니다.
Swagger Codegen vs OpenAPI Generator#
Swagger는 SmartBear사의 트레이드마크이며, Swagger Codegen은 그 안에 포함되어 있는 프로젝트입니다.
OpenAPI Generator는 Swagger Codegen 프로젝트를 포크(fork)하여 시작된 커뮤니티 주도 오픈소스 프로젝트입니다. 현재 40명 이상의 상위 프로젝트 기여자와 Swagger Codegen의 창립 멤버들이 함께 참여하고 있습니다.
OpenAPI Generator License#
OpenAPI Generator는 Apache License 2.0을 따르고 있습니다.
Apache License 2.0이란?#
Apache License 2.0에 따라 다음과 같은 권리가 부여됩니다
- 누구나 해당 소프트웨어에서 파생된 프로그램을 제작할 수 있음
- 저작권을 양도, 전송할 수 있음
- 부분 또는 전체를 개인적 또는 상업적 목적으로 이용 가능
- 재배포 시 원본 또는 수정한 소스코드를 반드시 포함시키지 않아도 됨
- 단, Apache License 버전 및 표기는 반드시 포함해야 함 (Apache License로 개발된 소프트웨어임을 명확히 표시)
OpenAPI Generator의 탄생 배경#
OpenAPI Generator의 공식 Q&A를 보면 프로젝트의 탄생 배경을 확인할 수 있습니다
버전 철학의 차이 Swagger Codegen의 창립 멤버들은 Swagger Codegen 3.0.0이 2.x의 철학과 너무 많이 다르다고 느꼈습니다. 두 개의 개별 브랜치(2.x, 3.x)를 유지 관리하는 오버헤드가 Python 커뮤니티에서 겪었던 것과 유사한 문제를 야기할 수 있다고 우려했습니다.
빠른 배포 주기 창립 멤버들은 사용자가 원하는 안정적인 배포 버전을 사용하기 위해 몇 달을 기다리지 않도록 더 빠른 배포 주기를 원했습니다.
- 주간 패치 배포 (Weekly patch releases)
- 월간 마이너 배포 (Monthly minor releases)
커뮤니티 주도 개발 커뮤니티가 주도하는 오픈소스 프로젝트 형식으로 진행하면 혁신과 신뢰성, 그리고 커뮤니티가 소유하는 로드맵을 확보할 수 있습니다.
위와 같은 이유들로 OpenAPI Generator 프로젝트가 탄생했습니다. OpenAPI Generator는 MySQL과 MariaDB의 관계와 유사한 느낌입니다.
Swagger Codegen에서 마이그레이션#
공식 문서에 따르면, 기존에 Swagger Codegen 2.x 버전을 사용하고 있을 경우 OpenAPI Generator로 편리하게 마이그레이션할 수 있습니다. OpenAPI Generator는 Swagger Codegen 2.4.0-SNAPSHOT 버전을 기반으로 하고 있기 때문입니다.
자세한 마이그레이션 방법은 공식 가이드를 참조하세요