iSyncBrain4.0을 설계하면서 API 문서 라이브러리에 대해 살펴보게 되었습니다. 막연하게 Spring Framework에서는 API 문서로 Swagger라는 걸 쓰는구나 정도로만 생각했었는데, 이번 기회를 통해 알게 된 내용을 포스팅하려고 합니다.

관련 내용을 찾아보며 Swagger, OpenAPI, Springfox, SpringDoc, RestDocs, Redoc 등 비슷한 듯 다른 많은 용어들로 인해 이해하는 데 어려움이 있었습니다. 이와 같은 수고를 덜어줄 수 있는 포스팅이 되면 좋겠습니다.

운영중인 iSyncBrain3.0의 API 문서는 Swagger를 사용하고 있습니다. 그리고 라이브러리는 springfox-boot-starter:3.0.0을 사용하고 있습니다.

springfox-boot-starter:3.0.0

springfox-boot-starter:3.0.0은 springfox-swagger2:3.0.0과 springfox-swagger-ui:3.0.0을 포함하고 있습니다. springfox-swagger2와 springfox-swagger-ui은 Swagger를 사용하기 위한 라이브러리입니다.

먼저, Swagger는 무엇일까요?

Swagger는 OpenAPI Spec 에 맞게 디자인하고 문서화하고 빌드하기 위한 도구들의 모음으로 다음과 같은 구성 요소로 이루어져 있습니다.

  • Swagger Editor – 브라우저 기반의 편집기로 OpenAPI spec 을 쉽게 작성할 수 있도록 도와줍니다.
  • Swagger UI - OpenAPI spec 문서를 배포하고 브라우저에서 예쁘게 표시할 수 있도록 해줍니다. swagger-ui 대신 아래에서 설명할 redoc 을 사용해도 됩니다.
  • Swagger Codegen - OpenAPI spec 에 맞게 Server 나 Client 의 stub code 를 생성해 줍니다. 개발자는 생성된 코드에 비즈니스 로직에 집중해서 구현하면 됩니다.

Swagger는 2010년대 초 Tam Wordnik이라는 사람이 개발하기 시작하였고, 2011년에 처음 릴리즈 되었습니다. 처음에는 Wordnik(회사) 자체 API용 UI로 개발되었고 2015년초에 SmartBear라는 회사에서 Swagger를 인수했습니다. 그리고 2015년 말, SmartBear는 Linux Foundation의 후원으로 OpenAPI Initiative에 Swagger를 기부하면서 OpenAPI Specification(OAS)로 이름이 변경되었습니다.

즉, Swagger Specification으로 불리던 용어는 이제 OpenAPI Specification가 되었습니다. Swagger는 이제 OpenAPI spec을 구현하기 위한 도구 세트(Swagger Editor, Swagger UI, SwaggerHub)로만 남겨진 이름이 되었습니다. 그런데 Swagger라는 브랜드명을 그대로 사용하고 있어 OpenAPI spec과 혼용되고 있었던 것입니다.

정리하면,
OpenAPI spec는 RESTful API 설계를 위한 업계 표준 사양을 나타내고,
Swagger는 SmartBear 도구 세트를 나타냅니다!

이어서 OAS(OpenAPI Specification)에 대해 더 알아보겠습니다.

OpenAPI, OAS, OpenAPI Spec, OpenAPI Specification는 같은 말입니다.

그러나 Open API는 다른 용어입니다! Open API는 누구나 사용될 수 있도록 API의 endpoint가 개방되어 있는 것을 뜻합니다. 기상청의 단기예보 조회 API, 우체국의 우편번호 API 등이 있고 다른 용어로 Public API라고 부르기도 합니다!

OAS(OpenAPI Specification)는 REST 명세 포맷으로 널리 사용되고 있는 포맷 중 하나이며, 프로그래밍 언어에 종속되지 않습니다. OAI(OpenAPI Initiative)에서 만들어졌고, OAS(https://openapis.org)에서 커뮤니티가 주도적으로 만들어가는 명세 포맷입니다.

OAS(OpenAPI Specification)는 json 이나 yml 형식으로 기술해야 하며 OAS 파일을 읽어서 디플로이 해주는 도구(Ex: swagger-ui)를 사용하면 아래와 같이 브라우저에서 편리하게 API 문서를 볼 수 있습니다.

swagger-ui

OAS(OpenAPI Specification)는 예전에는 Swagger spec으로 불렸으며 3.0부터 OpenAPI 3.0 Specification라는 이름으로 표준화되었습니다.

Swagger, OpenAPI가 이해되었고, 이제 Swagger를 사용하는 라이브러리를 살펴보겠습니다.

Spring Framework를 사용하는 프로젝트에서 Swagger를 이용해서 API문서를 쉽게 쓸 수 있도록 도와주는 라이브러리를 알아보려고 합니다. SpringFox, SpringDoc은 여기에 해당합니다.

Apache 2.0의 이 라이브러리의 변천사는 다음과 같습니다.

Swagger SpringMVC -> SpringFox Swagger2 -> SpringDoc OpenAPI UI

  1. swagger-springmvc
  2. springfox-swagger2
    • springfox-swagger2는 2015년부터 2018년 6월까지 지원됐다가 중단되었다가, 2020년 6월과 7월에 업데이트가 진행되었습니다. 현재 2020년 7월이 마지막 업데이트이며, 3.0.0까지 나왔습니다.
    • springfox-swagger2는 Config(설정 파일)와 Controller에 작성된 Annotation의 내용을 읽어 들여 json 또는 yaml 형태로 만들고, springfox-swagger-ui는 json을 html 형식으로 보여줍니다.
    • https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
  3. springdoc-openapi-ui

여기까지, Swagger, OpenAPI, Springfox, SpringDoc 등 여러 용어에 대해 API 문서 ‘spec’과 ‘spec을 사용하기 위한 라이브러리’를 구분하여 정리하였습니다.

Swagger를 검색하면 비교되는 RestDocs, Redoc은 무엇일까요? Swagger와 비교하여 간략하게 Spring REST Docs, Redoc을 알아보겠습니다.

Spring REST Docs

Spring REST Docs은 Swagger와 함께 대표적으로 API 문서를 자동화 도구입니다.

Spring REST Docs의 대표적인 장점은 테스트가 성공해야 문서 작성됩니다. 또한, 프로덕션 코드와 분리되어있기 때문에 Swagger 같이 Config 설정 코드나 어노테이션이 우리의 프로덕션 코드를 더럽힐 일이 없습니다.

Spring REST Docs

Redoc

Redoc은 OpenAPI Spec 파일을 읽어서 디플로이해주는 도구로 Swagger-UI 와 비슷한 역할을 수행합니다.

설치와 사용이 아주 간편한 장점이 있지만 swagger-ui 랑 달리 브라우저에서 API TEST 기능을 해볼수는 없는 단점이 있습니다.

Redoc은 local에서 작성한 API 가 제대로 문서화되었는지 빠르게 확인할 때 테스트할 때 유용합니다.

마치며

아이메디신에서는 iSyncBrain 4.0을 설계하고 있습니다. iSyncBrain 4.0은 마이크로 서비스 아키텍처(MicroService Architecture) 환경으로 구상하고 있습니다.

그리고 ISyncBrain4.0에서는 Swagger를 사용하기 위한 라이브러리로 SpringDoc을 사용하기로 하였습니다.

이전의 환경에서는 서버가 하나였기 때문에 해당 서버에 맞는 하나의 API 문서가 하나였습니다. 그러나 마이크로서비스 아키텍처는 서비스마다 서버가 분리되어 있습니다.

그렇기 때문에, 기존의 방식대로 각각의 서버에서 API 문서를 만든다면, 서비스마다 API 문서가 만들어질 것입니다. 그렇게 되면 서비스마다 API 문서가 분리되어 있어서 API 문서를 활용하는 면에서 각각 보아야 합니다.

예를 들어, 유저 서비스 담당 서버, 분석 서비스 담당 서버가 있다면 유저 서비스의 api 문서를 보기 위한 url, 분석 서비스의 api 문서 url이 따로 있게 되는 것입니다. 서비스 서버가 더 늘어난다면 api 문서도 늘어나게 되고, api 문서를 활용하는 면에서 점점 더 비효율적이 결과가 초래됩니다.

OpenApi spec을 지원하는 SpringDoc은 멀티 URL을 지원합니다.

springdoc

그래서 이 그림처럼 하나의 문서로 통합할 수 있어서 MSA 환경에서의 문제를 해결할 수 있게 되었습니다.

이상으로 포스팅을 마치겠습니다. 참고했던 링크들을 아래에 첨부하겠습니다.

추가적으로 원하는 내용들은 아래 링크를 통해 참고하셨으면 좋겠습니다.


https://swagger.io/docs/specification/about/
https://www.lesstif.com/software-engineering/openapi-swagger-redoc-106857823.html
https://gruuuuu.github.io/programming/openapi/
https://velog.io/@gillog/OASOpenAPI-Specification
https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi/
https://bcp0109.tistory.com/m/326
https://junho85.pe.kr/m/1583?category=177748
https://velog.io/@soyeon207/우당탕탕-Swagger-적용기
https://velog.io/@ychxexn/Swagger-다-같은-놈이-아니었다.-Springfox-vs-Springdoc
https://www.lesstif.com/software-engineering/openapi-swagger-redoc-106857823.html