Spring Cloud환경에서 Gateway에 Sagger 적용

📘서론

현재 MSA로 프로젝트를 진행하던 도중 Swagger를 적용시키고 싶어 해당 과정을 작성합니다.

 

 

1. 각 서비스 설정

1-1.  build.gradle에 swagger 의존성 추가

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2' // Swaggger 의존성

 

1-2. application.yml에 spring doc 설정

springdoc:
  default-produces-media-type: application/json
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
    display-request-duration: true

 

1-3. SwaggerConfig 설정

package com.gaebal_easy.client.hub.infrastructure.config;

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

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Hub Service API") // 서비스명 변경
                        .version("v1")
                        .description("Hub service API 문서입니다.")
                );
    }
}

1-4. (Security가 설정되어있다면)

Security가 설정되어있다면 관련 url들을 로그인 없이도 접근할 수 있도록 허용해주어야합니다.

.authorizeHttpRequests(auth -> auth
                        .requestMatchers( // swagger관련 url
                                "/v3/api-docs/**",
                                "/swagger-ui/**",
                                "/swagger-ui.html"
                        ).permitAll()

 

여기까지는 기존 모놀로틱과 큰 차이가 없습니다

2. Gateway설정

2-1. 의존성 추가

implementation 'org.springdoc:springdoc-openapi-starter-webflux-ui:2.3.0' // gateway는 webflux기반이라 해당 ui 사용해야함. Swaggger 의존성

 

차이점을 아시겠나요? Gateway는 WebFlux를 기반으로 동작하니 반드시 WebFlux 전용으로 구현하셔야합니다!

이것때문에 계속 404 🚨오류가 떴었어요

 

2-2. application.yml 파일 설정

여기서는 크게 2가지를 작성해야합니다.

1. SpringDoc설정

# swagger 설정
springdoc:
  swagger-ui:
    urls:
      - name: user-service
        url: /user-service/v3/api-docs
      - name: delivery-service
        url: /delivery-service/v3/api-docs
      - name: hub-service
        url: /hub-service/v3/api-docs
    path: /swagger-ui.html

크게 다르진 않지만 swaager-ui:urls설정을 통해 각 서비스의 swagger와 연결해줍니다!

 

2. gateway 프록시 설정

spring:  
   cloud:
    gateway:
      routes:
      	  # Swagger UI 허용 설정
        - id: user-service-swagger
          uri: lb://user-service
          predicates:
            - Path=/user-service/v3/api-docs
          filters:
            - StripPrefix=1
        - id: delivery-service-swagger
          uri: lb://delivery-service
          predicates:
            - Path=/delivery-service/v3/api-docs
          filters:
            - StripPrefix=1
        - id: hub-service-swagger
          uri: lb://hub-service
          predicates:
            - Path=/hub-service/v3/api-docs
          filters:
            - StripPrefix=1 # /hub-service/v3/api-docs 경로를 /v3/api-docs로 변경하여 전송

여기서 주의깊게 보셔야할부분은 StripPrefix=1 부분입니다. 

기존에 /hub-service/v3/api-docs 를 그대로 요청보내게되면 http://localhost:{hub-service-port}}/hub-service/v3/api-docs 로 요청이 전송되게 됩니다. 그렇기 때문에 hub-service를 제거하여 http://localhost:{hub-service-port}}/v3/api-docs 로 요청을 전송하면 올바르게 swagger 전송이 됩니다.

 

+ 추가

저는 중간에 다음과 같은 오류가 발생하였습니다

void org.springframework.web.method.controlleradvicebean 으로 오류가 발생하였습니다.

찾아보니 swagger에서 @RestControllerAdvice와 충돌이 나타나 발생하는 문제였습니다.

 @Hidden 어노테이션을 @RestControllerAdvice 클래스에 추가하여 해결 하였습니다.

 

참고☀️

https://medium.com/@AlexanderObregon/understanding-the-hidden-annotation-in-spring-for-hiding-openapi-endpoints-e3a81a99161c

https://velog.io/@clvl1004/Spring-Swagger-%EC%A0%81%EC%9A%A9%ED%95%98%EA%B8%B0