SpringBoot SpringDoc(OpenAPI)을 이용한 Swagger 그룹화, 전역인증&Parameter 설정

SpringDoc OpenAPI를 사용하여 Swagger에 표시되는 API들을 그룹화 시키는 방법과 JWT 인증을 전역으로 설정하는 방법을 알아본다. 

 

API 그룹화 

API가 많아질수록 Swagger 표시되는 API가 많아져서 가독성이나 관리가 힘들어지는 부분이 있다. 이럴 경우 API들을 package나 url path를 기준으로 그룹화 시킬 수 있다. 

먼저 그룹화하기 전에는 swagger에서는 일반적으로 아래와 같이 표현된다

그리고 그룹화를 group1, group2로 나눠서 적용하면 아래와 같이 표현된다. 우측 상단에 그룹을 선택할 수 있는 SelectBox가 뜨고 그룹에 따라 필터링해서 API를 조회가 가능해진다

 

아래는 그룹 적용을 위한 Bean 설정이다. 그룹화를 정의할 개수에 따라 GroupedOpenApi 빈을 등록해준다. 이때 각 그룹 별로 그룹이름과 필터링을 설정할 수 있다. patchsToMatch()로 url로 필터할 수 있고, packagesToScan() 으로 package단위로 설정할 수도 있다.

    @Bean
    public GroupedOpenApi group1() {
        return GroupedOpenApi.builder()
                .group("그룹1")
                .pathsToMatch("/group1/**")
             // .packagesToScan("com.example.swagger") // package 필터 설정
                .build();
    }

    @Bean
    public GroupedOpenApi group2() {
        return GroupedOpenApi.builder()
                .group("그룹2")
                .pathsToMatch("/group2/**")
                .build();
    }

 

참고로 그룹 설정은 application.yml에 아래와 같이 paths-to-match가 설정이 되어 있으면 yml설정이 우선순위가 높아서 그룹 설정의 필터링이 동작이 안된다. 그룹 설정 시에는 paths-to-match를 제거하고 설정한다.

springdoc:
  paths-to-match:
    - /**

 

전역 인증 설정(JWT)

Swagger 통해서 API호출 테스트 시 대부분 인증이 필요한데 각 API마다 인증을 설정하기가 너무 번거로운 작업이다. 이를 전역으로 설정하면 좀 더 편하게 API를 테스트 할 수 있다. 

기본적으로 OpenAPI 3에서는 API 호출 시 인증에 대한 처리를 위해 Security Scheme를 지원하는데 이 Security Scheme를 통해 설정을 진행한다. 빈 설정은 간단히 아래와 같다.

    @Bean
    public OpenAPI openAPI() {

        Info info = new Info()
                .version("v1.0.0")
                .title("API 타이틀")
                .description("API Description");

        // SecuritySecheme명
        String jwtSchemeName = "jwtAuth";
        // API 요청헤더에 인증정보 포함
        SecurityRequirement securityRequirement = new SecurityRequirement().addList(jwtSchemeName);
        // SecuritySchemes 등록
        Components components = new Components()
                .addSecuritySchemes(jwtSchemeName, new SecurityScheme()
                                .name(jwtSchemeName)
                                .type(SecurityScheme.Type.HTTP) // HTTP 방식
                                .scheme("bearer")
                                .bearerFormat("JWT")); // 토큰 형식을 지정하는 임의의 문자(Optional)

        return new OpenAPI()
                .info(info)
                .addSecurityItem(securityRequirement)
                .components(components);
    }

 

크게 2가지 설정이 있는데 SecurityRequirement를 통해 API호출 시 전역으로 설정한 인증정보가 요청 헤더에 포함이 되도록 하는 설정이다. SecurityScheme 를 통해서 전역 JWT 인증 설정을 등록한다. SecurityScheme 타입에는 HTTP 외에도 APIKEY, OAUTH2, OpenIdConnect 등이 있다. 

 

위와 같이 설정하고 SwaggerUI를 실행해보면 우측 상단에 Authorize 버튼이 표시되고 전역 인증 설정을 할 수 있다.

버튼을 클릭해서 인증정보를 입력한다.

그리고 API 호출 테스트를 할 때 요청정보를 확인하면 아래와 같이 요청헤더에 인증정보가 포함되어 호출이 된다.

 

전역 Parameter 설정

API 호출 시 매번 기본으로 포함되어야 하는 파라메타들도 전역으로 설정이 가능하다. 아래는 빈 설정이다.

    @Bean
    public OperationCustomizer operationCustomizer() {
        return (Operation operation, HandlerMethod handlerMethod) -> {
            Parameter param = new Parameter()
                    .in(ParameterIn.HEADER.toString())  // 전역 헤더 설정
                    .schema(new StringSchema()._default("1234567").name("AppID")) // default값 설정
                    .name("AppID")
                    .description("TEST AppID")
                    .required(true);
            operation.addParametersItem(param);
            return operation;
        };
    }

OperationCustomizer를 빈으로 등록해주면 되는데 빈 등록 시 여러개의 Parameter를 등록 가능하다. 위의 샘플 설정에서는 "AppID"라는 http 헤더 키값을 설정하는 부분으로 디폴트 값을 "1234567"로 설정했다. 파라메타 타입으로는 HEADER외에 QUERY, PATH, COOKIE 가 설정 가능하다. 

위 설정을 Swagger에서 실행해보면 아래와 같다.

그룹 설정과 함께 사용할 경우에는 GroupedOpenApi 빈 설정 시 OperationCustomizer를 파라메타로 선언해주고, addOperationCustomizer() 메소드에 등록해준다.

    @Bean
    public GroupedOpenApi group2(OperationCustomizer operationCustomizer) { // 파라메타 추가
        return GroupedOpenApi.builder()
                .group("그룹2")
                .pathsToMatch("/group2/**")
                .addOperationCustomizer(operationCustomizer)  // 전역 파라메타
                .build();
    }