MSA 아키텍처에서 API 문서 한 곳에서 관리하기

1. 개요

현재 Spring Cloud를 이용해서 MSA 프로젝트를 진행 중이다.

 

기존의 모놀리식 아키텍처는 하나의 프로젝트에서 모든 코드를 관리하기 때문에, 작성한 API를 하나의 API 문서에서 확인할 수 있다.

 

하지만 MSA는 각각의 도메인에 따라 프로젝트가 존재하고, 각각의 도메인마다 API 문서가 생성되는 문제가 발생했다. 

이 API 문서들을 사용하는 개발자들 입장에선 각각의 API 문서 주소를 알고 있어야 한다. 굉장히 불편하고 비효율적이다. 

 

 

MSA 환경에서 API 문서를 한 곳에 모아 관리하기 위해 방법을 찾아보았고 공유하고자 이 글을 작성한다. 

 

 

 

 

 

 

 

 

2. 의존성 추가

먼저 Swagger 사용을 위해 API Gateway에 의존성 추가를 해주자. 

 

여기 에서 각 버전에 맞는 의존성 확인이 가능하고, 나는 24.08 기준 가장 최신 버전인 2.6.0 버전을 사용했다. 

참고로 Spring Boot의 버전은 3.3.2 버전이다. 

 

// swagger
implementation 'org.springdoc:springdoc-openapi-starter-webflux-ui:2.6.0'

 

spring-doc 이 아니라 webflux spring doc임을 잊지말자.

 

 

 

 

 

 

 

3. YML 파일 설정

- apigateway-service의 application.yml 파일

springdoc:
  swagger-ui:
    urls[0]:
      name: user-service
      url: /user-service/v3/api-docs
    urls[1]:
      name: product-service
      url: /product-service/v3/api-docs
    urls[2]:
      name: order-service
      url: /order-service/v3/api-docs
    urls[3]:
      name: notification-service
      url: /notification-service/v3/api-docs
    urls[4]:
      name: board-service
      url: /board-service/v3/api-docs
    urls[5]:
      name: basket-service
      url: /basket-service/v3/api-docs
    use-root-path: true

 

위와 같이 각 micro service의 name과 url을 명시해주면 된다.

 

use-root-path: true 옵션은 root url로 접속 했을 때 swagger ui로 이동시켜주는 설정이고, 나는 편의를 위해 설정해줬다.  

 

 

 

 

 

 

 

4. 각 service에 swagger 설정

위에서와 마찬가지로 gradle 의존성 추가 후 yml 설정 파일에 아래와 같이 설정해준다.

 

 

- gradle

implementation group: 'org.springdoc', name: 'springdoc-openapi-starter-webmvc-ui', version: '2.2.0'

 

 

 

- user-service 의 application.yml 파일

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

 

 

 

각 서비스마다 swagger config 설정은 필요하다. 

@OpenAPIDefinition(
    info = @Info(title = "green-market user-service API 명세서",
        version = "v1"))
@Configuration
public class SwaggerConfig {

    // JWT + swagger
    @Bean
    public OpenAPI openAPI() {
        SecurityScheme securityScheme = new SecurityScheme()
            .type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")
            .in(SecurityScheme.In.HEADER).name("Authorization");
        SecurityRequirement securityRequirement = new SecurityRequirement().addList("bearerAuth");

        return new OpenAPI()
            .components(new Components().addSecuritySchemes("bearerAuth", securityScheme))
            .addServersItem(new Server().url("/"))
            .security(Arrays.asList(securityRequirement));
    }
}

 

 

 

이렇게 설정을 마치고 spring api gateway의 root url로 접근해보면 swagger가 잘 뜨고, 각 service도 잘 뜨는걸 확인할 수 있다. 

 

 

 

 

 

 

 

구글링 해봤을 때 보통은 swagger 와 restdocs를 합쳐 조금은 번거러운 구축 과정이 많았다.

 

물론 그 방법이 안정적인 측면에서 봤을 땐 더 좋지만 나는 토이 프로젝트를 진행하고 있기 때문에 위 방식을 택했다.