SpringBoot Swagger 3.x.x 적용하기

SpringBoot 3.x.x Swagger 적용

SpringBoot 버전을 3.0.0 이상 사용하는 프로젝트에서 Swagger를 도입할 때 사용해야하는 Swagger 라이브러리에 대해 알아보겠습니다.

 

기존 SpringBoot 3.0.0 이하 버전인 경우 이전 포스팅에서 확인하실 수 있습니다.

https://miiro-under.tistory.com/209

Swagger - REST API 명세 문서화

 

의존성 라이브러리 설정

SpringBoot 3.0.0 이상부터는 springfox가 아닌 springdoc-openapi-ui 라이브러리를 사용해야합니다.

 

이전 버전에서는 springfox를 이용해서 swagger 설정을 했습니다.

 

springfox와 springdoc 두 라이브러리 모두 Spring Framework를 사용하는 애플리케이션에서 Swagger를 이용해서 API 문서화를 쉽게 할 수 있도록 도와주는 라이브러리입니다.

 

[GitHub Link]

Springfox : https://github.com/springfox/springfox

Springdoc-OpenAPI : https://github.com/springdoc/springdoc-openapi

 

springfox의 경우에는 2020.07.14일 기준으로 더 이상 업데이트가 되지 않고 있습니다.

반면 Springdoc-OpenAPI의 경우에는 최근까지 릴리즈가 있고 SpringBoot 버전이 올라갈수록 사용해야할 거 같습니다.

 

 

springdoc을 사용한 swagger 적용

 

Swagger OpenAPI 3.0

Springdoc 라이브러리가 OpenAPI 3.0 스펙에 맞는 JSON을 자동으로 만들어주면, Swagger UI는 만들어진 JSON을 화면에 표시해주는 역할을 합니다.

 

springdoc-openapi-ui를 살펴보면 swagger-ui 를 포함하는 것을 확인할 수 있습니다.

• swagger-ui : 핵심 로직 구현
• springdoc-openapi : swagger-ui 를 추상화해서 더 잘 활용할 수 있게 해주는 라이브러리\

 

Swagger 적용(gradle)

dependencies {
    //swagger 3.0
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'
}

 

 

Swagger Config 설정

 

해당 Configuration 을 설정하면 Swagger 문서를 확인할 수 있다.

 

http://localhost:8080/swagger-ui/index.html#/

 

해당 링크에 접속하게 되면 아래 이미지와 같이 API 문서를 확인할 수 있습니다.

 

 

Swagger Config 설정 (JWT 권한 설정)

더불어 토큰 같은 인증과 권한이 필요한 경우가 있다.

이 경우에는 OpenAPI().components() 설정을 추가해줘야한다.

 

 

SecuritySchme 를 이용해서 토큰의 정보, Http 프로토콜, scheme 등 추가해줄 수 있다.

 

추가하고 다시 swagger.html 문서를 확인해보겠습니다.

 

 

오른쪽 상단에 Authorize 버튼이 생긴 것을 확인할 수 있다.

 

버튼을 클릭하면

 

 

인증과 권한과 관련된 토큰을 적을 수 있는 에디트박스가 생기는 것을 볼 수 있다.

해당 에디트 박스에 토큰을 적고 Authorize 버튼을 누르면 권한이 필요한 API를 사용할 수 있게 됩니다.

 

 

Swagger를 사용하기 위한 어노테이션은 해당 링크에서 확인하시면 됩니다.

https://blog.jiniworld.me/91

[Spring Boot Tutorial] 15. Open API 3.0 + Swagger v3 상세설정

 

 

Reference

springfox-swagger 공식문서

springdoc 공식문서