[Spring Boot] Spring Boot 3.x Swagger 적용기

오늘은 spring boot 3.x 버전에 swagger를 적용시켜 보려한다.

 

스웨거를 간단히 설명하자면.

개발자가 생성한 REST API를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다.

 

주의점

외부에 노출되면 안되는 API를 선정하여 숨김처리를 잘 하여야한다.

 

Spring Boot에는 swagger를 적용시킬 수 있는 라이브러리가 두개가 있다.

springfox, springdoc

• 2012 ~ 2015 : Swagger SpringMVC 이름으로 springfox 라이브러리가 많이 사용 됨.
• 2015 ~ 2018 : springfox-swagger 업데이트가 활발히 이루어짐.
• 2018 ~ 2020 : fox 업데이트가 진행되지 않아 springdoc 개발되어 많이 사용.

두 라이브러리 모두 Spring Framework를 사용하는 프로젝트에서 Swagger를 이용한 라이브러리이다.

 

하지만 나는 springdoc를 선택하였다.

 

이유 :

최근에도 업데이트한 이력이 있는데 23년 12월이다.

그리고 적용과 활용성도 springfox에 비하여 더 좋다 느꼇기 때문이다.

 

적용방법

 

1. 라이브러리 추가

https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui

maven
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

gradle
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'

 

2. 설정 파일 추가.

springdoc:
  swagger-ui:
    path: /swagger-ui
    groups-order: DESC
    operationsSorter: method
    disable-swagger-default-url: true
    display-request-duration: true
  api-docs:
    path: /swagger-ui/api-docs
  show-actuator: true
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  paths-to-match:
    - /**

 

3. Swagger UI Config 설정 파일 생성

package com.pet.care.pc.config;

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

@Configuration
public class SwaggerConfig {

  @Bean
  public OpenAPI openAPI() {
    return new OpenAPI()
      .info(
        new Info()
          .title("프로젝트 API")
          .description("프로젝트 관련 기능들을 제공합니다.")
          .version("1.0.0")
      )
      .components(
        new Components()
          .addSecuritySchemes(
            "bearer-key",
            new SecurityScheme()
              .type(Type.HTTP)
              .scheme("bearer")
              .bearerFormat("JWT")
          )
      );
  }
}

 

 

4. Spring Boot 실행

 - /swagger-ui접속

    - swagger-ui/index.html로 redirect

 

 

 

느낀점

Spring doc를 써보았는데 설정이 엄청 간편하고, 자동으로 rest api 문서들을 써주고, 그룹핑을 할 수 있어 관리에도 좋은 것 같다 

다들 적용 잘하여서 더 좋은 어플리케이션 만드세요!