[Spring boot] Spring Boot 3.x^ - Swagger 적용(2)

 

Spring Boot 3.x 버전 Swagger 적용

 

Spring boot 3.x 이전 버전에서의 Swagger 적용 및 Test 관련 사항은 아래 링크에서 확인하세요! 

https://lucas-owner.tistory.com/28

[SpringBoot] Swagger API 문서 자동화 간단 연동, 테스트하기

 

---

Spring Boot 를 3.x 이상 버전에서는 이전버전의 Swagger 와 별도로, Springdoc OpenAPI 로 통합되어 사용된다.

공식문서에 따르면, Java 17, Jakarta EE9 를 지원 한다고 명시해두었다.

 

해당 글에서는 전체 API 문서, 그룹화된 API 문서 2가지 설정 방식을 알아볼 예정이다.

Versions

2024.11 현재 2.6.0 이 최신 버전이며, 2.0.2 버전과 호환되는 기능들을 알아볼 예정이다.

Maven Repository

 

* build.gradle

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2' // Swagger

 

* Maven

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

 

버전은 2.0.2 를 사용할것이며, 2.0.2 이상 버전이면 어떤것을 사용해도 무방하다.(약간의 기능의 차이는 존재)

 

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

---

Configuration 설정

설정클래스의 경우 대략적인 큰 설정은 비슷하지만, OpenApi, GroupOpenApi 2가지로 설정 할 수 있다.

• openApi: 전체 API 문서를 관리한다.
• GroupOpenApi: 그룹별로 분리된 문서를 관리한다.
  • path, 지정 group 별로 API 를 분리해야할때 사용
  • 여러 API 그룹을 각각 관리.

 

Swagger 의 URL

• 기본 경로: http://localhost:8080/swagger-ui/index.html
• OpenAPI JSON 경로: http://localhost:8080/v3/api-docs

 

OpenAPI Configuration

@Configuration
public class SwaggerConfig {
    //http://localhost:8080/swagger-ui/index.html
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .components(new Components())
                .info(info());
    }

    private Info info() {
        return new Info()
                .title("Mongo Basic API")
                .description("Mongo API reference for developers")
                .version("1.0");
    }
}

전역적으로 관리 되어야 하는 OpenApi 설정의 경우 간단하게 설정이 가능하다.

components() 의 경우, 공통적으로 처리해야하는 Http Header, 스키마, 응답, 파라미터 등과 같은 공통요소를 정의하는 역할을 하며

API 문서를 재사용 가능하게 만들어 효율적으로 처리할 수 있다.

 

components() sample

@Configuration
public class OpenApiSecurityConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .components(new Components()
                        .addSecuritySchemes("BearerAuth", new SecurityScheme()
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("bearer")
                                .bearerFormat("JWT"))
                )
                .info(new Info()
                        .title("My Secure API")
                        .description("API documentation with security schemes")
                        .version("1.0"));
    }
}

// API Sample... 
@Operation(summary = "Get Secure Data",
           security = @SecurityRequirement(name = "BearerAuth"))
@GetMapping("/secure-data")
public String useSecurity() {
    return "Security Data";
}

 

openApi 전체 문서

 

GroupOpenAPI Configuration

해당 설정은 특정 경로나, 그룹을 각각 다른 문서로 관리할 수 있는 장점이 있다.

package com.lucas.mongobasic.config;

import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {
    //http://localhost:8080/swagger-ui/index.html
	@Bean
    public GroupedOpenApi groupedOpenApi() {
        return GroupedOpenApi.builder()
                .group("Product API")
                .pathsToMatch("/api/products/**")
                .addOpenApiCustomizer(productApiCustomiser())
                .build();
    }

    private OpenApiCustomizer productApiCustomiser() {
        return openApi -> openApi.info(new Info()
                .title("Product API")
                .description("API for managing products")
                .version("1.0"));
    }}
}

 

openAPI 와의 차이점이라고 한다면, 특정 API Path 를 지정해서 그룹화 한다는것과

Docs Description 부분은 OpenApiCustomizer 를 사용해야 한다는 차이가 존재한다. 

 

GroupedOpenAPi

 

다른 경로를 추가하고자 할때는 또하나의 Group을 Bean 으로 생성하면 된다. 

이때 group 의 String 값과, Method 명은 다른것으로 구분해줘야 한다.

@Bean
    public GroupedOpenApi groupedOpenApi() {
        return GroupedOpenApi.builder()
                .group("Product API")
                .pathsToMatch("/api/products/**")
                .addOpenApiCustomizer(productApiCustomiser())
                .build();
    }

    @Bean
    public GroupedOpenApi testGroup() {
        return GroupedOpenApi.builder()
                .group("Test API")
                .pathsToMatch("/api/test/**")
                .addOpenApiCustomizer(productApiCustomiser())
                .build();
    }

 

Docs Group 화