MSW 활용기 | (2) Mock API Schema 자동 생성하기 (Swagger UI 활용)

📌 이 글은 MSW 시리즈 중 2편입니다.
1편: MSW란?
3편: Plugin 방식으로 제공하기

---

1. 배경 (Motivation)

MSW를 활용해 모의 데이터를 만들 때는 실제 API 형식과 동일한 데이터 구조가 필요합니다.
하지만 이 과정을 사람이 직접 정의하다 보면 휴먼 에러 가능성과 반복 작업의 피로도가 큽니다.

👉 그래서 Swagger UI의 API Docs를 활용해 MSW & Storybook에서 활용 가능한 Mock API Schema를 자동 생성하도록 개선했습니다.

---

2. 목표 (Requirements)

• Swagger UI에서 제공하는 API Docs를 호출하여 스키마를 가져온다.
• 가져온 스키마를
  • 브라우저에서 즉시 활용하거나
  • 프로젝트에 파일로 저장할 수 있도록 한다.
• 파일이 존재하는 경우에는 재호출하지 않고 그대로 사용한다.
• 파일 저장 시 옵션으로 배열 요소의 최소/최대 개수를 지정할 수 있다.

---

3. 구현 과정 (Implementation)

3.1 Swagger API Docs 호출

Swagger UI에서 제공하는 엔드포인트에 요청을 보내 API 스키마를 획득합니다.

• 스키마를 직접 내려주지 않고, 모델 참조 형태로 제공 → 이를 파싱하는 로직이 필요했습니다.

3.2 파일 저장 방식

• Tag 단위 저장: 특정 태그에 속한 모든 API 스키마를 개별 파일로 저장
• 경로 단위 저장: 특정 API 경로를 입력해 스키마 저장 가능
  • 배열 요소가 포함된 경우 → 최소/최대 개수 지정 가능

3.3 활용

• Mock 데이터는 MSW에서 API 응답으로 사용
• 동시에 Storybook 환경에서도 그대로 활용 가능

---

4. 시행착오 (Troubleshooting)

4.1 스키마 제공 문제

문장으로는 단순히 “API Docs를 호출해서 스키마를 가져온다” 라고 했지만,
실제로 Swagger UI는 응답 스키마를 곧바로 제공하지 않았습니다.

• HTML 템플릿 기반 예시만 제공
• 응답 구조는 $ref로 모델을 참조하는 형태

➡️ 이 부분을 처리하기 위해 크게 두 가지 방법을 고민했습니다.

1. Java 같은 모델 형식을 프로젝트에 직접 구현
2. API Response를 순환 참조하며 구조를 탐색

결과적으로 2번(순환 참조 방식)을 선택했습니다.

• 최악의 경우 복잡도가 O(n^5)까지 증가 가능
• 하지만 실제 API 스키마 크기가 작아 충분히 처리 가능

4.2 개선 기능 추가

• Tag 단위 스키마 저장 기능
• 배열 요소의 최소/최대 개수 지정 옵션

---

5. 결과 (Result)

아래는 실제 실행 화면입니다.

---

6. 고민거리 (Reflection)

Mock 데이터 특성상 실제 데이터와 달라서 UI 표시 결과가 어색할 때가 있었습니다.
이를 해결하기 위해

• 실제 데이터를 DB에 저장하거나,
• 샘플 데이터를 직접 구축하는 방식도 고려했지만

그렇게 되면 Mock 데이터의 장점(빠른 모의 API 구성)이 사라진다는 우려가 있어 보류 중입니다.

---

7. 배운 점 (Learning)

• Swagger Docs는 스키마를 직접 제공하지 않는다는 점을 체험적으로 학습
• 순환 참조 로직 구현을 통해 데이터 파싱 복잡도와 성능 고려를 실습
• Mock API 자동화를 통해 MSW & Storybook 활용성을 크게 개선

---

이번 작업은 단순한 자동화 이상의 의미가 있었습니다.
“백엔드 스펙 변경에 따라 Mock API도 자동으로 갱신되는 구조” 를 만들 수 있었기 때문입니다.