[코프링] spring-boot/kotlin swagger 적용하기

---

 

API 스펙 공유하는데 스웨거(swagger)만한 솔루션이 없습니다. 이번에 하는 코프링 프로젝트에도 스웨거를 적용시켜볼까 합니다.

 

일단 이런거 추가할 때는 build.gradle.kts에 추가해야겠죠? 구글링 해보면 아래와 같이 dependencies를 추가하는 것을 볼 수 있습니다.

implementation("io.springfox:springfox-swagger2:2.9.2")
implementation("io.springfox:springfox-swagger-ui:2.9.2")

3.x.x 버전도 있긴 한데 2.9.2를 가장 많이 사용하는 것 같습니다. 

아마 2.9.2 뒤로 2년동안 없뎃이 없다가 나와서 그렇겠죠? 그런데 이렇게 추가하고 config도 추가해주거나 아니면 다른 dependency를 더 추가하는 경우가 많은데, 스웨거도 stater 패키지가 나와서 이거 하나만 세팅해주면 쉽게 사용할 수 있습니다.

 

implementation("io.springfox:springfox-boot-starter:3.0.0")

한방에 사용하는김에 버전도 3.0.0을 사용해줍니다 ㅋㅋ 

 

이제 실행하려고 하면 아마 에러가 나시는 분이 있을 겁니다. 스프링 부트 2.6 이상에서는 에러가 발생하는데 application.yml에 다음을 추가합니다.

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

혹은 스프링부트 버전을 2.5로 낮춰도 됩니다.

 

이제 실행을 하고 ~/swagger-ui/로 접속하면 기본 스웨거 화면이 보입니다.

 

자동으로 swagger가 적용된다.

저희가 설치한 패키지가 자동으로 @controller나 @entity 어노테이션을 검색해서 스웨거 페이지를 만들어줍니다. 저는 Message controller를 만들어놨기 때문에 컨트롤러가 하나 보이고, error controller는 디폴트로 생기는 건가 보네요. 이제 화면에 보이는 메시지를 쪼꼼 디테일하게 바꿔주기 위해 스웨거 어노테이션을 사용해봅시다.

 

스웨거 어노테이션 사용하기

컨트롤러 위에 @Api 어노테이션을 사용하면 스웨거에서 컨트롤러 위에 나오는 제목을 바꿀 수 있습니다.

 

Message에서 한글로 바꼈쥬?

 

추가로 이것저것 한글로 알아보기 쉽게 어노테이션을 달아줍니다.

 

보기 편해졌쥬?

 

@Api까지 쓰면 어떤 어노테이션들이 있는지 나오기 때문에 취향에 맞게 스웨거 페이지를 꾸며주면 되겠다. 

 

끗~