Spring swagger 적용 방법 (springdoc-openapi)

Swagger란?

Swagger는 Open Api Specification(OAS)을 위한 프레임워크입니다. OAS는 RESTful 웹 서비스를 설명, 생산, 소비 및 시각화하기 위한 기계 판독 가능 인터페이스 정의 언어에 대한 사양을 뜻합니다. 직접 소스 코드를 보지 않고도 서비스를 이해할 수 있도록 해주는 것입니다.

Swagger는 개발한 REST API를 편리하게 문서화해주고, 이를 통해서 관리 및 제 3의 사용자가 편리하게 API를 호출해보고 테스트 할 수 있는 프로젝트입니다. 다만, 주의할 점은 운영환경과 같은 외부에 노출되면 안되는 곳에서의 사용은 주의해야 합니다.

 

Spring Boot에서는 springfox와 springdoc을 통해 Swagger를 사용할 수 있습니다.

springfox의 마지막 업데이트 날짜는 2020년 7월 14일으로 경우 현재 개발이 중단된 상태이고 springdoc-openapi의 마지막 업데이트 날짜는 2023년 8월 7일입니다. 예전과 같은 경우 springfox를 활용해 많이 swagger를 사용했다고 알고 있지만, 아무래도 지속적인 업데이트가 이루어지고 있는 springdoc을 활용하는 것이 이후에 더 좋을 것이라 예상되어 springdoc-openapi를 활용해 swagger를 사용해보기로 결정했습니다.

 

 

0. gradle dependency 설정

maven repository에서 가장 많이 사용하고 있는 SpringDoc OpenAPI UI 버전을 찾아 gradle dependency에 추가해주었습니다.

 

springdoc-openapi-ui

dependencies {
    ...
    // https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui
    implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.7.0'
}

 

...

 

하지만 찾아보니 위의 springdoc-openapi-ui는 spring boot v2까지만 지원을 한다고 합니다. 저와 같은 경우 spring boot v3을 사용하고 있는 관계로 다른 버전을 사용해주도록 하겠습니다.

 

springdoc-openapi-starter-webmvc-ui

dependencies {
    ...
    // https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui
    implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.1.0'
}

 

1. swagger ui

gradle dependency에 추가해준 것만으로 {server url}:{port}/swagger-ui.html 를 통해 swagger에 접속할 수 있습니다.

 

"hi" 를 반환하는 간단한 Controller를 구성한 결과 다음과 같이 해당 api에 대한 설명을 확인할 수 있습니다.

swagger ui

오른쪽 위의 Try it out을 통해 실제 서버로 요청을 보내고 응답을 받아볼 수 있습니다.

swagger ui를 통해 api 요청

 

2. 추가 설정

properties 설정을 통해 여러가지 설정을 할 수 있습니다. springdoc-openapi 문서 를 확인하시면 다양한 설정값들을 살펴볼 수 있습니다.

springdoc 설정값

여러 설정값 중 springdoc.api-docs.enabled, springdoc.swagger-ui.enabled를 통해 swagger를 외부에 노출시킬지 말지 정할 수 있습니다.

이러한 설정값들을 통해 swagger의 custom url 설정, cache와 같은 설정을 할 수 있습니다.

 

3. 명세 상세 설정

@OpenAPIDefinithion을 통해 Swagger 상세 설정을 할 수 있습니다.

@OpenAPIDefinition(
        info=@Info(
                title = "spring api 명세서",
                description = "Swagger API 명세서",
                version="v0.0.1"
        )
)
@Configuration
public class SwaggerConfig {
}

Swagger 상세 설정

 

4. 어노테이션

springdoc-openapi는 Swagger v3 Annotaion을 활용하고 있으므로 이를 참고해 사용하면 됩니다.

 

@Tag

name: 태그의 이름, description: 태그에 대한 설명

Tag에 설정된 이름이 같은 것끼리 하나의 api 그룹으로 묶습니다. 주로 Controller Class나 Method에 설정합니다.

 

@Schema

description : 스키마 설명, defaultValue : 기본값 설정

schema에 대한 정보를 작성할 수 있습니다. dto 클래스들에 정의해서 사용하면 각 속성의 타입, 기본값들을 정의해줄 수 있습니다.

 

@Operation

summary: api 설명, description: api 설명

api 동작에 대한 명세를 작성할 수 있습니다. Controller 메서드에 정의해 사용합니다. summary는 api가 펼쳐지지 않은 상태에서의 간략한 설명이고 description은 펼쳐진 상태에서의 api 설명을 작성할 수 있습니다.

 

@Parameter

name: 파라미터 이름, description: 파라미터 설명, in: 파라미터 위치

파라미터 요소에 대한 설명을 작성할 수 있습니다.

 

 

 

이번 포스팅에서는 Swagger api의 사용 방법에 대해 간단히 다뤄보았습니다. 현재 api 명세를 공유하고 있지는 않아서 더 자세하게 알아보지는 않았던 것 같습니다. 나중에 좀 더 공부해서 제대로 사용한다면, api 명세를 통해 Frontend 개발자나 아니면 다른 제 3자가 이를 통해 확실하게 확인할 수 있다는 점이 Swagger의 장점이 될 수 있을 것입니다.

 

 

 

 

 

출처: https://jeonyoungho.github.io/posts/Open-API-3.0-Swagger-v3-%EC%83%81%EC%84%B8%EC%84%A4%EC%A0%95/