Swagger UI란?

Swagger UI란 간단하게 말해서 문서화 Open API인데요 개발자라면 문서화가 얼마나 중요한지 알고 계시리라 생각됩니다. 왜냐하면 개발은 혼자만의 힘으로 하는 것이 아닌 팀적으로 개발하기 때문에 서로의 커뮤니케이션을 위해선 팀 회의를 통한 규칙 또는 내용들을 문서를 통해 정리할 필요가 있습니다.

이런 문서화 API는 중요한 만큼 여럿 존재합니다. 흔히 알고 계시는 Java doc도 있고 저번 스크럼에 저가 소개한 Har Exploer도 문서화 API 중 하나입니다. 이번 시간에는 실무에서 가장 널리 쓰이고 예전부터 즐겨 사용해왔던 Swagger UI의 사용 방법과 설정 방법에 대해 설명드리겠습니다.

Swagger UI를 지금부터 짧게 swagger라고 부르겠습니다. swagger는 spring boot에 포함되어 있지 않습니다. 아직 부족한 부분이 존재하는 지, 대중화는 되어 있지만 다른 문서화 api들 또한 swagger만큼 잘 되어있어서 그런지 아직은 spring boot library에 내제되어 있지 않습니다.

현재는 Open API로 존재하는데요 따라서 저희가 사용하기 위해서는 dependency를 gradle에 추가해줘야합니다. 이런 swagger에 환경 설정 방법에 대해 잘 알려주는 공식 문서가 있는데요 바로 springDoc입니다 아래의 링크로 확인하실 수 있습니다.

OpenAPI 3 Library for spring-boot

문서를 확인하면 친절하게 어떻게 사용해야하는 지 (비록 영어지만..) 잘 알려주고 있습니다.

시작을 위해서 추가해야하는 dependency의 양식이 잘 나와있는데요. 처음이신 분들은 조금 당황하실 수 있습니다. 요즘 즐겨 사용하는 gradle 형식이 아닌 maven 형식으로 나와있기 때문입니다.

안타깝게도 Spring doc는 gradle 형식을 지원하지 않는데요😂 maven 형식만 보고도 gradle 형식으로 간단하게 바꿀 수 있습니다. 아래는 gradle 형식으로 바꾼 code 입니다.

//spring 3.x.x에 대한 dependency
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0

혹시나 스프링 2.7.x 버전을 사용하시고 있는 분들을 위해 아래는 해당 버전의 dependency도 추가해봤습니다.

//spring 2.7.x에 대한 dependency
implementation 'org.springdoc:springdoc-openapi-ui:1.6.12'

위의 dependency를 추가하고 서버를 실행함으로써 swagger ui를 확인할 수 있습니다. swagger를 확인하기 위해 따로 URL을 설정할 수도 있지만 대부분의 사람들은 ‘swagger 사용하고 있어? 그럼 확인해보자’라고 말하면서 자연스럽게 검색하는 URL이 있는데요 바로 아래의 URL입니다

"http://localhost:8080/swagger-ui.html"

gradle을 추가하고 위의 URL로 들어가면 다음과 같은 화면이 잘 나옵니다.

아직 Controller에 아무것도 구현해놓지 않았기 때문에 위와 같이 여백의 페이지가 나옵니다. 간단하게 테스트를 한번 해보기 위해 MainController에 테스트 코드를 작성했습니다.

실행해보면 다음과 같이 잘 나옵니다.

그런데 swagger를 보신 분들이라면 좀 허전한 느낌을 받으실 것 같습니다. 아무 설명이 없기 때문입니다. 문서화를 하는 이유 중 하나가 이해를 더 잘하기 위함인데 아무 설명이 존재하지 않으면 슈크림 없는 붕어빵과 같다고 생각이 듭니다.

설명을 추가하는 방법도 여러가지가 있습니다.

위와 같이 @Schema 등 swagger annotation을 사용해서 추가하는 방법도 있습니다. 근데 저는 개인적으로 문서화를 하기 위해 원래 있던 순수한 코드에 대해 덕지덕지 어노테이션을 붙이는 건 가독성과 효율성 때문에 좋아하지 않습니다.

그래서 어떤 방법을 사용하려고 하냐면 아까 위에서 말씀드렸던 Java doc에 대해 기억하시나요? Java doc와 swagger를 결합해서 사용해보려고 합니다. Spring doc를 보시면 다음과 같이 Javadoc support 부분이 존재합니다.

https://springdoc.org/#javadoc-support

저가 spring 2.7.0을 사용해서 다음과 같은 코드를 gradle에 추가해주면 됩니다.

implementation 'org.springdoc:springdoc-openapi-javadoc:1.6.12'
annotationProcessor 'com.github.therapi:therapi-runtime-javadoc-scribe:0.15.0'

spring 3점대는 잘 모르겠지만 공식 문서를 잠깐 보니 annotationProcessor만 넣어주면 되는 것 같은데 사용하실 분들은 확인해보시면 좋겠습니다.

코드에 아래와 같이 Java doc 주석을 추가하고

실행하면 다음과 같이 설명이 추가된 api를 볼 수 있습니다.

저번 주에 저가 잠깐 data-rest api에 대해 소개한적이 있는데요 Spring Data REST는 도메인 모델과 repository를 분석해서, 자동으로 RESTful API를 제공해줍니다. 현재 코드엔 data-rest를 추가한 상태인데 swagger에서는 보이지 않습니다. 이 부분에 대한 설명도 Spring doc에 존재합니다.

간단히 gradle에 다음의 코드만 추가하면 됩니다.

implementation 'org.springdoc:springdoc-openapi-data-rest:1.6.12'

이러고 실행하면 다음과 같이 data-rest가 추가된 페이지를 확인할 수 있습니다.

마지막으로 아래는 swagger와 Har Exploer를 비교한 사진입니다.

Har Exploer 또한 gradle를 추가하고 url로 들어가면 바로 확인할 수 있을 뿐더러 data-rest api들 또한 추가 없이 바로 확인할 수 있는 장점을 가지고 있습니다.

//URL 주소 : **<http://localhost:8080/api**>
implementation 'org.springframework.data:spring-data-rest-hal-explorer'

어떤 API를 사용하든 장단점이 있으니 본인이 맘에 들고 편한 API를 사용하거나 팀 프로젝트라면 팀 회의를 통해 정한 API를 사용하면 될 것 같습니다.

읽어주셔서 감사합니다.