[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 기준)

 

저같은 경우는 AccessToken과 RefreshToken을 모두 검사하기 때문에 아래 코드에서와 같이 RerfeshToken도 입력할 수 있도록 SecuritySchema를 추가하였습니다. 만약 AccessToken으로만 인증을 한다면, SecuritySchema를 한 개만 추가하시면 됩니다.

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.info.Info;
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";
        String refreshTokenName = "Refresh-Token";

        SecurityRequirement securityRequirement = new SecurityRequirement().
                addList(securityJwtName)
                .addList(refreshTokenName);

        // Swagger INFO 설정
        Info info = new Info()
                .version("v1")
                .title("슈케팅 API 타이틀")
                .description("API Description");

        // 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)
                )
                .addSecuritySchemes(refreshTokenName, new SecurityScheme()
                        .name(refreshTokenName)
                        .type(SecurityScheme.Type.APIKEY)
                        .in(SecurityScheme.In.HEADER)
                );


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

    }
}

 

4. Controller 단에서 설정 예시

 

5. DTO 단에서 설정 예시

 

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

 

7. 기타

어노테이션 방식으로 스웨거 적용시키기

package music.is.my.life.musicismylife.configuration;

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import lombok.RequiredArgsConstructor;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@SecurityScheme(
        name = "Bearer Authentication",
        type = SecuritySchemeType.HTTP,
        bearerFormat = "JWT",
        scheme = "bearer"
)
@OpenAPIDefinition(
        info = @Info(title = "EDM 플랫폼 서비스 API 명세서",
                description = "EDM 아티스트들을 위한 커뮤니티형 음원 공유 플랫폼",
                version = "v3"))
@RequiredArgsConstructor
@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi chatOpenApi() {
        String[] paths = {"/miml/**"};

        return GroupedOpenApi.builder()
                .group("EDM 플랫폼 API v3")
                .pathsToMatch(paths)
                .build();
    }
}