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 타입이 일관되게 유지되며, 관리가 쉬워집니다!
