[Springboot] springdoc 을 사용하여 Swagger 설정하기 - 1

<목차>

1. Swagger ?
2. springdoc - springfox
3. Setting

 

[Swagger ?]

API를 개발함에 있어, 명세 관리는 필수이다.

해당 API가 어떤 로직을 수행하는지 설명하고, 이 로직을 수행하기 위해 어떤 값을 필요로 하며, 이 로직의 결과로는 어떤 값이 생성되는지를 정리한 자료가 있어야 API를 사용함에 있어 불편이 줄어들 수 있기 때문이다.

 

이런 API 명세는 개발 과정에서 지속적으로 업데이트 해주어야 하며, 매우 번거롭고 많은 시간이 소요되는 업무이다.

이러한 불편함을 줄여주는 Swagger 프로젝트에 대해 알아보자.

---

[springdoc - springfox]

스프링부트 환경에서 Swagger 를 사용할 수 있는 대표적인 라이브러리로는 Springfox 와 Springdoc 이 있다.

각 라이브러리는 아래와 같은 특성을 가지고 있으며, Springfox의 경우 현재 업데이트가 거의 이루어지지 않기때문에 Springdoc 을 많이 사용하는 추세이다.

특징	Springfox	Springdoc
지원 스펙	Swagger 2, OpenAPI 3	OpenAPI 3
설정 난이도	상대적으로 복잡	간단
최신 기능 지원	업데이트가 상대적으로 느림	최신 OpenAPI 표준 지원
의존성	많은 의존성	적은 의존성
확장성과 커스터마이징	높은 확장성과 커스터마이징 가능	제한된 커스터마이징 가능
커뮤니티와 문서화	많은 문서와 커뮤니티 지원	상대적으로 적음

 

---

[Setting]

셋팅 환경은 다음과 같다.

[Env]
Springboot 2.7.18
Maven
JDK 11

 

 

1. 의존성 추가

 

pom.xml

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.8.0</version>
</dependency>

 

2. 끝?

현재 본인이 구동한 서버 URL에 다음 경로만 붙여보자.

{server-url}/swagger-ui/index.html

별다른 설정을 해준 것이 없음에도, 아래 같이 작성된 API에 대한 명세를 확인할 수 있다.

Default Swagger UI

 

이대로 끝내긴 아쉬우니, 조금 더 보기 좋게 설정해보자.

 

3. ApiInfo 설정 (SwaggerConfig)

나만의 설정을 위해, SwaggerConfig 파일을 생성해주자.

다음과 같은 정보들을 커스텀 할 수 있다.

    @Configuration
    public class SwaggerConfig {

        @Bean
        public OpenAPI openAPI() {
            return new OpenAPI()
                    .components(new Components())
                    .info(apiInfo());
        }

        private Info apiInfo() {

            //Contact
            Contact contact = new Contact();
            contact.name("이름").email("메일주소");

            return new Info()
                    .title("JPA Simple Example Swagger")	//타이틀
                    .description("JPA Simple Example")	//설명
                    .contact(contact)			//Contact
                    .version("ver. 1.0.1");			//버전 정보
        }
    }

 

이제 타이틀 영역은 잘 작성되었다.

 

이렇게 Swagger 에 대한, 기본적인 설정은 완료되었다.

다음 포스팅에서, Swagger 를 API 명세서로서의 역할을 잘 수행하기 위해 API 별 셋팅 방법을 알아보자.