MSA(Microservices Architecture) 환경에서 Spring Boot + Next.js API 타입을 일치

MSA(Microservices Architecture) 환경에서 Spring Boot + Next.js 를 사용하면서 API 타입을 일치시키는 가장 효과적인 방법은 Spring Cloud를 활용한 OpenAPI(Swagger) 관리입니다.

Spring Cloud를 이용하면 각 마이크로서비스의 API 스펙을 중앙에서 관리할 수 있어, Next.js와 같은 프론트엔드 애플리케이션이 일관된 타입을 유지할 수 있습니다.

---

✅ Spring Cloud 기반 OpenAPI 통합 방법

MSA 환경에서는 각 마이크로서비스가 개별적으로 OpenAPI 문서를 관리하면 서비스 간 API 타입이 불일치할 위험이 있습니다.
이를 해결하기 위해 Spring Cloud Gateway + OpenAPI Aggregation을 활용하여 모든 서비스의 API를 중앙에서 관리하는 방법을 사용합니다.

---

1️⃣ API Gateway(Spring Cloud Gateway) + OpenAPI 통합

Spring Cloud Gateway를 사용하여 여러 개의 마이크로서비스의 API를 하나의 OpenAPI 문서로 통합할 수 있습니다.

✅ (1) Spring Cloud Gateway 설정

📌 spring-cloud-starter-gateway 추가

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>

📌 Gateway에서 각 마이크로서비스 라우팅 설정 (application.yml)

spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: http://user-service:8081
          predicates:
            - Path=/api/users/**
        - id: order-service
          uri: http://order-service:8082
          predicates:
            - Path=/api/orders/**

➡️ 각 마이크로서비스의 API를 Gateway를 통해 호출하도록 설정

---

✅ (2) OpenAPI 문서 통합 (Swagger Aggregator)

각 마이크로서비스가 개별적으로 OpenAPI 문서를 제공하면 API Gateway에서 이를 하나의 문서로 병합해야 합니다.

📌 springdoc-openapi-gateway 추가

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.3.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

📌 Swagger 문서 자동 병합 설정 (application.yml)

springdoc:
  swagger-ui:
    path: /swagger-ui.html
  api-docs:
    groups:
      enabled: true
  swagger-ui:
    urls:
      - name: User Service
        url: http://user-service:8081/v3/api-docs
      - name: Order Service
        url: http://order-service:8082/v3/api-docs

➡️ 각 서비스의 OpenAPI 문서를 Gateway에서 통합하여 제공
➡️ 프론트엔드는 Gateway의 OpenAPI를 사용하여 타입을 자동 생성할 수 있음

---

2️⃣ Next.js에서 OpenAPI 타입 자동 생성

API Gateway에서 제공하는 OpenAPI 문서를 활용하여 Next.js의 TypeScript 타입을 자동 생성할 수 있습니다.

✅ (1) OpenAPI 타입 생성기 설치

npm install openapi-typescript axios

✅ (2) API Gateway의 OpenAPI에서 TypeScript 타입 생성

npx openapi-typescript http://api-gateway:8080/v3/api-docs -o src/types/api.ts

✔ src/types/api.ts 파일이 자동 생성되며, 모든 마이크로서비스의 API 타입이 포함됨.
✔ 프론트엔드에서 API 호출 시 일관된 타입을 유지할 수 있음.

---

✅ (3) API 호출 함수 만들기 (타입 적용)

import axios from "axios";
import type { paths } from "../types/api"; // 자동 생성된 타입 import

const API_BASE_URL = "http://api-gateway:8080/api";

export const getUser = async (id: number) => {
    const response = await axios.get<paths["/api/users/{id}"]["get"]["responses"]["200"]["content"]["application/json"]>(
        `${API_BASE_URL}/users/${id}`
    );
    return response.data;
};

➡️ API 타입이 자동으로 적용되므로, 타입 불일치 문제를 해결할 수 있음

---

✅ 결론

1️⃣ Spring Cloud Gateway를 사용하여 API 통합
2️⃣ Swagger Aggregation으로 모든 마이크로서비스의 OpenAPI 문서 병합
3️⃣ Next.js에서 API Gateway의 OpenAPI 문서를 기반으로 타입 자동 생성

➡️ 이 방식이면 MSA 환경에서도 API 타입이 일관되게 유지되며, 관리가 쉬워집니다!