OpenAPI 기반 Type generator 사용 시 타입 변화로 인한 프론트/백엔드 결합도 제거

 

0. 개요

API 문서를 작성하고 유지보수하는 데 지나치게 많은 공수가 들어가고 있다고 느꼈다.

초기에 문서를 작성할 때는 문제가 없지만, 요구사항 변화나 hotfix 배포 과정에서 수정할 일이 생기면

API 문서가 점차 뒤처지기 시작한다.

 

그러다 버그 수정이나 관련 기능 변경이 발생하면 다시 API 문서를 참고하게 되지만,

이미 문서는 최신 상태가 아닌 경우가 대부분이었다.

이런 문제를 해결하기 위해 OpenAPI Specification(OAS)을 기반으로 타입을 자동 생성하는 도구를 도입했다.

 

1. 적용 및 문제점

타입 생성 도구 도입 후 초반 개발 속도는 크게 개선되었으며, 무엇보다 API 스펙 변경 시 클라이언트가 즉시 변화를 감지할 수 있다는 장점이 있었다. 하지만 시간이 지나면서 새로운 문제가 드러났다.

• 클라이언트가 서버에서 생성된 타입에 지나치게 의존하게 되었고
• 서버에서 리팩토링으로 클래스 명이 변경되면 클라이언트도 반드시 대응해야 하는 문제가 발생
• 타입 생성 규칙 때문에 비슷한 이름의 클래스가 많아질 경우
• 클라이언트에서 어떤 타입이 어떤 API에 매핑되는지 구분이 어려워지는 문제가 생김

즉, 서버와 클라이언트 간의 경계가 사라지고 양쪽이 강하게 결합되는 구조가 되었다.

 

2. 해결방안

1) API Contract 안정화(Model 이름 고정)

• SpringDoc / Swagger 의 @Schema(name="...")로 스키마 이름 명시
• 서버 내부 클래스명/패키지는 자유롭게 변경해도 OpenAPI 스펙은 고정

→ 내부 리팩토링 시에도 API 스펙은 변화 없음

→ 클라이언트에 영향 X

 

 

2) 클라이언트 타입 Wrapping Layer 도입 (Generated 타입 직접 사용 금지)

• 클라이언트에서는 generated 타입을 직접 쓰지 않고
• 프로젝트 내부에서 안정적인 타입 alias를 제공
• generator가 타입 명칭을 변경해도 전체 코드 영향 최소화

→ 내부 리팩토링 시 클라이언트의 wrapping layer만 수정 

 

 

 

3. 결과

• 서버와 클라이언트 간 의존도가 현저히 줄어들어 양쪽 팀의 개발 자유도 증가
• API 계약은 그대로 유지하면서도 내부 리팩토링이 가능해져 서버 개발 생산성 향상
• 타입 변경으로 인한 클라이언트 수정 비용을 대폭 절감하여 협업 효율 증가
• API 구조가 명확히 분리되어 장기적으로 안정성 및 유지보수성 향상