[Spring Boot] Springdoc 라이브러리를 통한 Swagger 적용

1. build.gradle에 의존성 추가

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

2. application.yml 설정

springdoc:
  swagger-ui:
    # 각 API의 그룹 표시 순서
    # path, query, body, response 순으로 출력
    groups-order : DESC

    # 태그 정렬 순서
    # 알파벳 순 정렬
    tags-sorter: alpha

    # 컨트롤러 정렬 순서
    # method는 delete - get - patch - post - put 순으로 정렬
    operations-sorter: method

    # swagger-ui default url인 petstore html의 비활성화 설정
    disable-swagger-default-url: true

    # swagger-ui에서 try 했을 때 request duration을 알려주는 설정
    display-request-duration: true

    # 모델 확장 깊이를 2단계로 설정
    default-models-expand-depth: 2

    # 개별 API 호출의 모델 확장 깊이를 2단계로 설정
    default-model-expand-depth: 2
  api-docs :
    # OpenAPI 명세서의 경로를 /api/docs로 설정
    # 기본값 : /v3/api-docs
    path:  /api-docs

  # Spring Actuator의 엔드포인트를 Swagger에 표시
  show-actuator: true

  # API에서 사용할 기본 미디어 유형을 application/json으로 설정
  default-consumes-media-type: application/json
  default-produces-media-type: application/json

  # Swagger UI에서 출력 포맷을 pretty-print 방식으로 설정
  writer-with-default-pretty-printer: true

  # Swagger API에서 Spring의 ModelAndView 객체를 허용
  model-and-view-allowed: true

  # Swagger 문서에 포함할 경로 패턴을 지정
  paths-to-match: /**

3. SwaggerConfig 생성(JWT 기준)

package com.ssu.ssuketing.common;

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

@Configuration
public class SwaggerConfig {

    private static final String BEARER_TOKEN_PREFIX = "Bearer";

    @Bean
    public OpenAPI openAPI(){
        // API가 JWT 인증을 요구
        String securityJwtName = "JWT";
        SecurityRequirement securityRequirement = new SecurityRequirement().addList(securityJwtName);

        // Swagger에서 사용하는 보안 스키마(인증 방식)를 정의
        // SecurityScheme.TYPE.HTTP 타입의 Bearer 토큰 인증 방식을 사용, Bearer 포맷으로 JWT를 지정
        Components components = new Components()
            .addSecuritySchemes(securityJwtName, new SecurityScheme()
                .name(securityJwtName)
                .type(SecurityScheme.Type.HTTP)
                .scheme(BEARER_TOKEN_PREFIX)
                .bearerFormat(securityJwtName)
            );

        return new OpenAPI()
                .addSecurityItem(securityRequirement)
                .components(components);

    }
}

 

4. Controller 단에서 설정 예시

 

5. DTO 단에서 설정 예시

 

6. 실행 ⇒ http://localhost:8080/swagger-ui/index.html 접속