Swagger 통합

MSA기반으로 프로젝트를 진행하다 보면 정말 많은 서비스 모듈이 생기게 됩니다. 포스트맨과 같은 API 테스트 툴을 사용하면 상관없지만 Swagger를 사용하는 경우 각 서비스에 맞게 Swagger UI를 실행해야 하며 각각의 주소를 기억해야 하는 번거로움이 있습니다.

보통 마이크로서비스는 API Gateway를 통해 연결되며, gateway의 주소만 public IP로 공개하는 것이 일반적이므로 GateWay에서 라우트하여 한 곳에서 모든 서비스의 api docs를 통합하여 볼 수 있도록 설정.

 

 

설정

GateWay application.yml

springdoc:
  enable-native-support: true
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    use-root-path: true
    urls[0]:
      name: Order Service
      url: /order-service/v3/api-docs
    urls[1]:
      name: Delivery Service
      url: /delivery-service/v3/api-docs
    urls[2]:
      name: Hub Service
      url: /hub-service/v3/api-docs
    urls[3]:
      name: Company Service
      url: /comp-service/v3/api-docs
    urls[4]:
      name: Slack Service
      url: /slack-service/v3/api-docs
    urls[5]:
      name: AI Service
      url: /ai-service/v3/api-docs
    urls[6]:
      name: User Service
      url: /user-service/v3/api-docs

- id: hub-service
          uri: lb://hub-service
          predicates:
            - Path=/api/hubs/**
          uri: lb://hub-service
          predicates:
            - Path=/hub-service/api/hubs/**
          filters:
            - RemoveRequestHeader=Cookie
            - RewritePath=/hub-service/api/hubs/(?<segment>.*), /api/hubs/$\{segment}

 

의존성 implementation 'org.springdoc:springdoc-openapi-starter-webflux-ui:2.3.0'

 

각 서브모듈 서비스

springdoc:
  api-docs:
    version: openapi_3_1
    enabled: true
    path: /hub-service/v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html

 

의존성 implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'

 

트러블슈팅

Config Server의 사용

하나의 서버에서 모든 서비스의 컨피그를 관리하는 부분에서 시도를 했음.

Spring Bus + RabbitMQ를 통해 컨피그의 변경사항을 각 서비스에 알리는 부분을 구현.

하지만 스웨거를 처음 적용해보는 과정에서

컨피그를 자주 변경해야하고 테스트 해야했고, 그 상황에서 Bus가 잘 되고 있는지도 신경써야했음.

결국 불안정적인 환경도 신경쓰느라 원인파악도 어려웠음.

Config Server 사용을 중단하고 추후 리팩토링 과제로 전환

잘못된 엔드포인트 설정

각 서비스의 실제 포트로 docs를 요청하면 잘 나왔으나 Gateway 포트로는 에러가 났음.

>> GateWay에서 설정해준 docs의 URL과 각 서비스에서 설정한 docs의 URL을 일치시켜야 함.

RewritePath 설정

각 서비스는 설정대로 ‘http://localhost:19090/hub-service’ 등으로 라우트 됨.

그런데 API를 테스트 할때에도 ‘hub-service’가 붙어 요청됨.

RewritePath=/hub-service/api/hubs/(?<segment>.*), /api/hubs/$\{segment}

• 요청 경로가 /hub-service/api/hubs/로 시작하면, 그 뒤의 경로(나머지 부분)를 segment라는 변수에 저장.
• 이 변수를 /api/hubs/$\\{segment}로 변경하여 새로운 경로를 만듦.