[Swagger3] 1. springdoc-openapi를 이용한 Swagger3 설정하기(+Swagger 옵션)

 

Swagger 기본 설정 및 Swagger에서 제공하는 기본 옵션에 대해 알아보자!

 

 

 

1) build.gradle 

dependencies 안에 openapi-ui 추가

//swagger
implementation 'org.springdoc:springdoc-openapi-ui:1.7.0'

 

 

2) application.yaml

springdoc:
    api-docs:
    	path: /api-docs			# api-docs url: localhost:8080/api-docs
        groups:
        	enabled: true		# group 허용
    swagger-ui:
    	path: /index.html		# swagger url : localhost:8080/swagger-ui/index.html
        enabled: true
        groups-order: ASC		# group 정렬 오름차순
        tags-sorter: alpha		# tag 정렬 알파벳순
        operations-sorter: alpha	# api 정렬 알파벳순
        display-request-duration: true
        doc-expansion: none		# swagger tag 리스트 펼치기
    cache:
    	disabled: true
    override-with-generic-response: false
    model-and-view-allowed: true	# returnType ModelAndView도 Swagger에 노출
    default-produces-media-type: application/json
    default-consumes-media-type: application/json

 

swagger-ui:

1) path: swagger-ui를 접속할 path 설정 

2) groupd-order: group 정렬 방법 설정 

    - ASC : 오름차순

    - DESC : 내림차순

3) tags-sorter: tag 정렬 방법

    - alpha : 알파벳순

4) operations-sorter: api 정렬 방법

    - alpha : 알파벳순

5) display-request-duration : "Try it out"을 실행 후 api 실행 시간 표시(milliseconds) 

    - false(default) : 실행시간 미표시

    - true : 실행시간 표시

6) doc-expansion: swagger 각 태그별 api 리스트 펼치기/접기

    - list(default) : tag만 펼치기

    - full : tag와 operation 모두 펼치기

    - none : 모두 접기

 

swagger application.yaml

 

 

 

3) SwaggerConfig.java 설정(그룹 설정)

1) @Profile 어노테이션을 이용하여 운영에서 Swagger 미사용하도록 설정하기

2) GroupedOpenApi를 이용하여 path, package 별로 그룹 나누기 (그룹 포함시키기, 제외시키기)

import org.springdoc.core.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;

@Configuration
public class SwaggerConfig {

    @Bean
    public GroupedOpenApi group1() {
    	String[] packagesToScan = {"com.example.project.admin"};
        
        return GroupedOpenApi.builder()
        		     .group("admin")
                             .packagesToScan(packagesToScan)
                             .build();
    }
    
    @Bean
    public GroupedOpenApi group2() {
    	String[] pathsToMatch = {"/customer/**"};
        String[] pathsToExclude = {"/customer/mypage/**", "/customer/login/**"};
        
        return GroupedOpenApi.builder()
        		     .group("customer")
                             .pathsToMatch(pathsToMatch)	// group에 포함시킬 paths
                             .pathsToExclude(pathsToExclude) // group에서 제외시킬 paths
                             .build();
    }
    
    @Bean
    public OpenAPI springOpenApi() {
    	return new OpenAPI().info(new Info()
        			        .title("forB's API")
                                        .description("Swagger API 설정 프로젝트")
                                        .version("v0.0.1"));
        								
    }
	
}

 

Swagger 우측 상단에서 그룹별로 확인할 수 있다.