Spring boot 2.7.18에서 swagger 설정하기 <1>

 

프로젝트를 함께 만들고 있는 프론트엔드 개발자들과 효율적인 커뮤니케이션을 위해서 스웨거를 사용하려고 합니다.

적용하면 만난 이런 저런 이슈 사항들을 기록해보았습니다.

 

프로젝트 버전

spring boot: 2.7.18

springfox: 3.0.0

springdoc-openapi-ui: 1.7.0

 

---

 

 

요즘은 gpt에게 물어봐서 대략적인 흐름을 파악하고, 한 단계씩 검증하며 적용하는 방법으로 작업을 하는 것 같습니다.

아래 처럼 3단계면 된다고 하는데, 당연히 한번에 안될것이라 예상하고 가보겠습니다.

 

 

 

 

1. SpringFox 사용

 

Step1. 의존성 추가하기

아래의 의존성을 추가하기 전에 공식 홈페이지를 한번 찾아가봅니다.

implementation 'io.springfox:springfox-boot-starter:3.0.0'

 

깃헙 레포를 찾아보니 아래처럼 추가하라고 되어있습니다.

gpt가 맞는 정보를 준 것 같습니다.

 

의존성만 추가하고 실행하니 바로 에러가 반겨주네요.

다음 스텝들까지 설명해주면 더 좋을텐데, 의존성 추가 이야기만 적혀있습니다.

오래된 스프링 관련 프로젝트들은 문서가 친절하지 않은 것 같아서 조금 아쉽습니다.

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException: Cannot invoke "org.springframework.web.servlet.mvc.condition.PatternsRequestCondition.getPatterns()" because "this.condition" is null

 

 

Step2. 설정 클래스 만들기

오류는 잠시 두고, gpt가 제안한 설정클래스를 먼저 만들어보겠습니다.

@Configuration
@EnableSwagger2
public class SwaggerConfig {
  @Bean
  public Docket apiDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.your.package"))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(getApiInfo());
  }

  private ApiInfo getApiInfo() {
    return new ApiInfo(
            "My REST API",
            "Some custom description of API.",
            "API TOS",
            "Terms of service",
            new Contact("Name", "www.example.com", "email@example.com"),
            "License of API",
            "API license URL",
            Collections.emptyList());
  }
}

 

추가해봤지만 동일한 에러가 계속 발생합니다.

그럼 이제 에러를 해결해보겠습니다.

 

 

검색을 하다보니 spring doc으로 migration하라는 이야기가 심심치 않게 보입니다.

 

 

 

 

spring doc는 무엇이고 spring fox와는 무슨 차이가 있는지 확인을 해봅니다.

간단하게 이야기하면 둘 다 swagger를 쓰기 위한 툴인데, fox는 업데이트를 하지 않은지 오래되엇고 doc가 최신에 많이 사용되고 있다는 것 같습니다. 그럼 doc를 사용하는 쪽으로 방향을 틀어봅니다.

 

 

 

---

 

2. SpringDoc OpenAPI

 

위에서 처럼 전체적인 과정을 먼저 한번 찾아보겠습니다.

전체 흐름에는 큰 차이가 없어 보입니다.

 

 

Step1. 의존성 추가

기대를 가지고 공식 홈페이지를 찾아가 보겠습니다.

fox보다 훨씬 모던한 공식 홈페이지를 가지고 있습니다.

첫줄에 보니 Spring Boot 2.x and 1.x는 springdoc-openapi v1.7.0이 최신이라고 합니다.

 

 

 

maven 기준으로만 작성되어 있으니 gradle 에서 추가하기 위해서 maven repository에서 찾아봅니다.

 

 

 

1.7.0 버전을 가장 많이 사용하는 것을 확인할 수 있습니다.

 

 

implementation 'org.springdoc:springdoc-openapi-ui:1.7.0'

 

 

Step2. 기본 설정

이번에는 의존성을 추가하자마자 바로 실행이 됩니다. 

Getting Started가 부실하다고 생각하고 있었는데, no additional config is need 라고 써있는 그대로 아무런 설정을하지 않아도 바로 동작을 확인할 수 있습니다.  /swagger-ui.html 혹은 /swagger-ui/index.html 로 접속이 가능합니다.

 

 

 

Step3: 커스터마이징

공식 홈페이지에서 제공한 예제 링크입닌다.

레포에서 설정파일과 진입파일을 살펴보면 추가하는 방법이 적혀있습니다.

 

gpt가 주는 예제와 크게 다르지 않아서 gpt와 함께 조금 더 진행해보겠습니다.

 

 

잠깐 주제에서 벗어나서 왜 SwaggerConfig가 아니고 OpenApiConfig라는 이름을 쓰는지 궁금증이 생겼습니다.

이 OpenAPI라는 것이 개발자들 사이에서 말하는 그 OpenAPI라는 건가?

 

제가 gpt를 좋아하는 가장 큰 부분은 궁금한 부분들을 나의 눈높이에서 해결할 수 있다는 점입니다 ㅎㅎ

다시 커스터 마이징으로 돌아가서, 우선 기본 데이터를 입력해보고 어떻게 반영되는지 먼저 확인해보겠습니다.

 

@Configuration
public class OpenApiConfig {

  @Bean
  public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info().title("My API")
                    .version("v1")
                    .description("This is a sample Spring Boot RESTful service using springdoc-openapi and OpenAPI 3."));
  }
}

 

 

위의 정보를 추가하니 스웨거 ui 페이지의 헤더 부분이 변경이 되는 것을 확인할 수 있습니다.

 

 

저는 환경별로 운영 / 개발 / 로컬을 나눠서 사용할 수 있게 정리해봤습니다.

@Configuration
public class OpenApiConfig {

  @Value("${swagger.title}")
  private String title;

  @Value("${swagger.version}")
  private String version;

  @Value("${swagger.description}")
  private String description;

  @Bean
  public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info().title(title)
                    .version(version)
                    .description(description));
  }
}

 

 

다음 편에서 실제로 api에 대한 내용을 작성해보겠습니다.

 

 

 

---

[글 대표 이미지 출처]
https://swagger.io/solutions/api-development/