[BEInternship] Swagger 적용하기

junghan·2023년 8월 12일

BE 인턴십

목록 보기

2/9

Swagger란?

Swagger란 개발한 Rest API를 편리하게 문서화 해주고, 이를 통해서 관리 및 제 3의 사용자가 편리하게 API를 호출해보고 테스트 할 수 있는 프로젝트입니다.

Spring Boot에서는 간단하게 springfox-boot-starter 를 gradle dependencies에 추가 함으로 사용할 수 있다.
다만, 주의할 점은 운영환경과 같은 외부에 노출되면 안되는 곳에서 사용할 땐 주의 해야 합니다.

💡 Dev환경에서만 사용하도록하자!

스웨거의 문서화 라이브러리

springdoc vs springfox

두 라이브러리 모두 Spring Framework를 사용하는 프로젝트에서 Swagger를 이용해 API 문서를 쉽게 쓸 수 있도록 해주는 라이브러리입니다.

2012 ~ 2015 : Swagger SpringMVC 이름으로 springfox 라이브러리가 많이 사용 됨
2015 ~ 2018 : springfox-swagger 업데이트가 활발히 이루어짐
2018 ~ 2020 : fox 업데이트가 진행되지 않아 springdoc 개발되어 많이 사용 됨
2020 ~ 2022 : springfox도 다시 업데이트 시작하여 springdoc 비슷하게 활용 중
2023 ~ 현재 : 현재는 springdoc가 보편적으로 사용중인 것 같다.

너로 정했다! springdoc

프로젝트에는 springdoc을 선택했습니다. 공식문서가 읽기 편했고, API 그룹핑 설정이 더 간단하다고 합니다.

작성일 기준 더 활발히 업데이트 되고 있기도 하고, 대세를 따라가는 것이 인지상정..

Swagger OpenAPI 3.0

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

(출처 : springdoc 공식문서)

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

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

프로젝트에 적용해보자

build.gradle 파일

springdoc 의존성을 추가해준다.

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

application.properties

기타 경로 설정을 할 수 있다. ~~yml파일로 해도 된다~~

# Swagger springdoc-ui Configuration
springdoc.packages-to-scan=com.wanted.jungproject
springdoc.default-consumes-media-type=application/json;charset=UTF-8
springdoc.default-produces-media-type=application/json;charset=UTF-8
springdoc.swagger-ui.path=swagger-ui-jung.html
springdoc.swagger-ui.tags-sorter=alpha
springdoc.swagger-ui.operations-sorter=alpha
springdoc.api-docs.path=/api-docs/json
springdoc.api-docs.groups.enabled=true
springdoc.cache.disabled=true

CONFIG

향후 API가 많아졌을 때, 토큰설정이나 복잡한 설정을 config로 나눠 관리해주면 좋을 것 같다.

package com.wanted.jungproject.config;

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

/**
 * Swagger springdoc-ui 구성 파일
 */
@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI openAPI() {
        Info info = new Info()
                .title("데모 프로젝트 API Document")
                .version("v0.0.1")
                .description("데모 프로젝트의 API 명세서입니다.");
        return new OpenAPI()
                .components(new Components())
                .info(info);
    }
}