Springdoc OpenAPI(4) - API 그룹화

Dong·2025년 3월 23일

Spring

목록 보기

4/4

이번 포스트에서는 Swagger 상에 여러 API를 그룹화하는 방법에 대해 알아보겠다.

그룹화하는 방법은 Configuration을 통해서 하는 방법과 application.yaml을 통해서 하는 방법이 있다.
또한 두 방법 모두 Group의 이름과 해당 그룹에 해당하는 API를 매칭하는 설정이 있다.

API 매칭

API를 매칭하는 방법에는 path와 package가 있다.
두 방법 모두를 설정한 경우는 교집합에 해당하는 API만 매칭된다.

Path

URL 기준으로 매칭
match(포함), exclude(제외)

Package

패키지 기준으로 스캔
match(포함), exclude(제외)

1. Configuration

@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi allApi(){
        return GroupedOpenApi.builder()
                .group("전체")
                .pathsToMatch("/**") // URL
                .packagesToScan("org.example.swagger.controller") // 패키지
                // .pathsToExclude() // URL 제외
                // .packagesToExclude() // 패키지 제외
                .build();
    }
    

    @Bean
    public GroupedOpenApi customerApi(){
        return GroupedOpenApi.builder()
                .group("고객")
                .pathsToMatch("/customer/**") // URL
                .build();
    }

    @Bean
    public GroupedOpenApi productApi(){
        return GroupedOpenApi.builder()
                .group("상품")
                .pathsToMatch("/product/**") // URL
                .build();
    }
}

2. application

# display-name을 설정하지 않으면 group에 작성한 string 값으로 대체된다.
springdoc:
  group-configs:
    - group: all
      display-name: 전체
      paths-to-match:
      - /**
      packages-to-scan:
      - org.example.swagger.controller
      # paths-to-exclude: # URL 제외
      # packages-to-exclude: # 패키지 제외
      
    - group: customer-api
      display-name: 고객
      paths-to-match:
      - /customer/**
      
    - group: product-api
      display-name: 상품
      paths-to-match:
      - /product/**