SpringBoot version3 의 Springdoc GroupedOpenApi 설정 방법

1. gradle 설정

	// spring doc
//	implementation 'org.springdoc:springdoc-openapi-ui:1.6.14'
	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'

SpringBoot version 3.XX에서 위에 주석 처리한 설정을 사용하면, Whitelabel Error Page 가 나온다.
https://stackoverflow.com/questions/75574324/spring-boot-version-3-0-0-springdoc-openapi-ui-dont-work
아래의 링크를 가보면, SpringBoot version 2.XX에서 사용하는 Springdoc을 implementation한 것을 알 수 있다.
SpringBoot 3.XX에서의 올바른 gradle import는 org.springdoc:springdoc-openapi-starter-webmvc-ui를 사용해야 한다.

2. yml 설정

springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    path: /swagger-ui/index.html
    groups-order: DESC
    doc-expansion: none
    tags-sorter: alpha
    operationsSorter: method
    disable-swagger-default-url: true
    display-request-duration: true

• api-docs.enabled: true -> Swagger 사용 여부 설정, default = true
• path : Swagger 접속 path 설정
• tags-sorter : 태그 정렬 기준
• operations-sorter : 태그 내 API의 정렬 기준
  정렬 기준은 기본 값은 컨트롤러 내 정의한 api 메서드 순
  alpha(알파벳 오름차순), method(http method)
• doc-expansion : tag와 operation을 펼치는 방식 설정
  “list”, “full”, “none” 으로 설정 가능
  “none” 설정 시 모두 닫힌 상태로 문서 열람

3. SwaggerConfig 설정

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI getOpenApi() {

        return newOpenAPI().components(newComponents())
        .info(getInfo()); 

    }

    private Info getInfo() {
        return new Info()
            .version("1.0.0")
            .description("COMMERCE REST API DOC")
            .title("COMMERCE");
    }
}

위와 같이 OpenApi를 빈으로 등록해주는 것으로 Swagger파일이 만들어진다.

• info : OpenApi의 기본 설정
• version : Swagger 문서 버전 표기
• description : Swagger 문서 설명
• title : Swagger 문서 제목

4. groupOpenApi 설정

@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi getItemApi() { 
    
        return GroupedOpenApi
            .builder()
            .group("item")
            .pathsToMatch("/api/item/**")
            .build();

    }

    @Bean
    public GroupedOpenApi getMemberApi() {

        return GroupedOpenApi
            .builder()
            .group("member")
            .pathsToMatch("/api/member/**")
            .build();

    }

    @Bean
    public OpenAPI getOpenApi() {

        return new OpenAPI().components(new Components())
            .info(getInfo()); 

    }

    private Info getInfo() {
        return new Info()
            .version("1.0.0")
            .description("COMMERCE REST API DOC")
            .title("COMMERCE");
    }
}

Springdoc의 경우 위와 같이 GroupedOpenApi를 만들 수 있는데, 기본 SwaggerConfig만 설정했을 때와 달리, GroupedOpenApi를 설정하면, select a definition을 통해 API들을 구룹별로 제공한다.

애플리케이션이 충분히 크다면, Springdoc의 GroupedOpenApi를 통해 API를 분류하여 API spec을 문서화할 수 있다는 장점이 있다.

• group : Swagger문서에서의 definition 이름
• pathsToMatch : url을 통해 Swagger문서의 그룹을 나눈다