springboot Gateway swagger 적용 (MSA)

사용이유?

 

MSA로 환경을 구축하면, 각 서비스마다 서버가 띄어져있을 것입니다.

 

그 서비스마다 Swagger를 설정하고 이를 개별로 확인하는 것은 상당히 비효율적이라고 생각합니다.

 

각 서비스에 도달하기전 Gateway 서비스가 제어를 하는데, 이 Gateway 서비스에 swagger를 적용하면 됩니다.

 

MSA로 어느정도 구축된 환경이라고 생각하고 진행하겠습니다.

 

또한

 

이 환경을 기준으로 설명하겠습니다.

 

- Java 17

- spring boot 3.2.3

- gradle

- yaml

 

 

설정

 

 

1. 의존성 주입

https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webflux-ui

 

위의 링크에서 최신 버전의 의존성 확인이 가능합니다.

이글 기준, 저는 최신버전인 2.5.0 버전을 사용하였습니다.

 

 

 

 

2. yml 설정

springdoc:
  swagger-ui:
    urls[0]:
      name: Account API
      url: http://게이트웨이 주소/api/account/v3/api-docs
    urls[1]:
      name: Advisor API
      url: http://게이트웨이 주소/api/advisor/v3/api-docs
    urls[2]:
      name: MTNW API
      url: http://게이트웨이 주소/api/mtnw/v3/api-docs
    urls[3]:
      name: Payment API
      url: http://게이트웨이 주소/api/payment/v3/api-docs
    urls[4]:
      name: Ticket API
      url: http://게이트웨이 주소/api/v1/ticket/v3/api-docs

 

해당 설정은 swagger에서의 마이크로서비스와 매칭해주는 작업입니다.

 

springdoc:
  swagger-ui:
    use-root-path: true

 

게이트웨이에 위와 같은 설정을 해주면, 게이트웨이 서버에 접속하였을때, 바로 swagger 주소로 안내해줍니다.

 

 

여기까지가 Gateway 서비스 yml에 설정이였습니다.

 

 

3. 마이크로서비스 설정

 

각 서비스에도 gateway에서 설정했던 것처럼 springdoc을 추가해줍니다.

 

https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webflux-ui

(게이트웨이 에서 설정해줬던 버전과 일치하면 좋습니다)

 

springdoc:
  api-docs:
    version: openapi_3_1
    enabled: true
    path: /api/advisor/v3/api-docs
  enable-spring-security: true
  default-consumes-media-type: application/json
  default-produces-media-type: application/json

 

위의 설정은 api-docs 버전 및 사용 여부 설정, security와 타입에 대한 설정입니다.

 

4. 스웨거 설정예시

 

@RequiredArgsConstructor
@Configuration
@OpenAPIDefinition(
        info = @Info(
                title = "advisor API",
                version = "v1",
                description = "advisor API 입니다."
        )
)
public class SwaggerConfig {

    @Bean
    public OpenAPI openAPI() {

        return new OpenAPI()
                .addServersItem(new Server().url("/"));
    }

}

 

위의 코드는 스웨거의 설정입니다.

 

여기서 OpenApi 객체에서 서버의 url을 /로 설정한 이유는 서버를 배포했을때

서버가 https로 설정되어있을경우 swagger를 통해 API 요청 시,
브라우저 정책에 의하여 http, https 통신간 cors같은 문제가 발생할수있기때문에

url을 root경로로 설정 하였습니다.

 

 

5. 스웨거 설정완료 화면