Spring boot에 Swagger 적용하기

이번 게시글에서는 SpringDoc과 Swaager를 이용하여 API 문서를 생성하는 방법에 대하여 알아보려고 합니다. 

저는 Spring security가 적용되어있는 환경을 기준으로 적용하였습니다. 

 

# build.gradle 의존성 추가하기 

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

 

 

# Open API Bean으로 등록하기 

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI api() {
        OpenAPI openAPI = new OpenAPI()
                            // 보안 관련
                            .addSecurityItem(new SecurityRequirement().addList("Bearer Authentication"))
                            .components(new Components().addSecuritySchemes("Bearer Authentication", createAPIKeyScheme()))
                            .info(apiInfo());


        return openAPI;
    }

    private Info apiInfo() {
        Info info = new Info()
                        .title("API TITLE")
                        .description("DESCRIPTION")
                        .version("0.0.1");

        return info;
    }

    private SecurityScheme createAPIKeyScheme() {
        return new SecurityScheme().type(SecurityScheme.Type.HTTP) // 스키마 유형 HTTP
                .bearerFormat("JWT") // 토큰 형식
                .scheme("bearer"); // 스키마 이름
    }

}

 

# Spring Security를 적용한 경우 페이지 접근을 위한 인증 여부 관련 설정 추가하기 

@Bean
    public SecurityFilterChain filterChain(HttpSecurity security) throws Exception {
        security.
                // 인증 필수 관련 페이지 설정
                .authorizeHttpRequests(
                    requests -> requests
                            // swagger 경로는 인증을 요구하지 않음
                            .requestMatchers("/v3/**", "/swagger-ui/**").permitAll()
                            .anyRequest().authenticated()
                );
        return security.build();
    }

 

# 컨트롤러에 swagger 관련 코드 추가하기

// 컨트롤러에 대한 설명
@Tag(name = "", description = "")
public class DomainController {
	// 메서드에 대한 설명 
    @Operation(summary = "제목", description = "설명")
    public void test() {
    
    }
}

 

# Swagger 접속하기

🔎 Swagger 접속 후 문서작동 여부 확인

Ex. 로컬에서 실행한 경우 : http://localhost:8080/swagger-ui/index.html#/