Spring project에 Swagger 적용하기

2023년 12월 12일 TIL

플젝을 진행하면서 swagger 한번 적용해보겠다고 하루를 날렸다.

Swagger

사용한 목적

이 전 프로젝트에서 다른 동료가 swagger 를 이용하여 테스트 환경을 구축하는 걸 보았고, 사용 해봄으로써 사용성에 반했다. 또한 당근 서버밋업에서 현직 개발자들도 swagger 를 이용하여 문서화하고 소통한다는 발표를 들었기 때문에 반드시 내 기술로 만들겠다는 목표를 세웠다.

Swagger 기능

• API의 문서화 : 해당 서비스 내의 RESTful API 가 자동으로 문서화된다.
• API 테스트 : 문서화 된 API 를 swagger 상에서 실시간으로 테스트 해볼 수 있다.

의존성 추가

본 프로젝트에선 build.gradle 을 사용했다.

dependencies {

    // Swagger (Springdoc OpenAPI)
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0'

}

dependencies 에 swagger 를 이용하기 위해 springdoc - openapi 를 추가해준다.
여기 저기 찾아보sl Springfox 도 있길래 욕심껏 이것 저것 다 넣고 돌렸더니 충돌났다.
Springfox 와 springdoc 내부에 있는 API가 많이 다르다.
그 사이에서 해결하지 못하고 한참 고생했다. gpt4는 별 도움이 되지 않았다...
하나만 골라 사용하는걸로.

SwaggerConfig

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

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                    .title("My API")
                    .version("1.0.0")
                    .description("This is a sample API documentation"));
    }
}

common 패키지 내부에 SwaggerConfig 를 만들어 줬다.
GroupedOpenApi 라던지 ApiInfo 라던지 Docket 이라던지
springdoc 에서 지원하지 않는 API를 GPT 녀석이 추천해주는 바람에 정말 쌩고생했다.

url

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

개인적인 생각이지만 swagger 적용한 후 배포를 하게 된다면 배포를 통해 접근해볼 수 있지 않을까 싶다.

어노테이션

apidocs swagger 어노테이션 링크