[NHN FORWARD 22] API 우선 접근 방식과 OpenAPI Specification

API First를 구체화한 방법론이 API Design First로, 설계 문서인 API 컨트랙트를 먼저 만들고 비즈니스 계약처럼 이해관계자 동의를 얻은 뒤 개발에 들어가는 것이 핵심 원칙이다. 이를 통해 문서·클라이언트 SDK 자동 생성 등 상호 운영성과 개발 효율이 오른다고 짚는다.

리눅스 재단 산하 OpenAPI Initiative가 주도하는 표준 스펙으로, 스웨거에서 출발해 3.x까지 발전한 역사를 정리한다. 스펙(OAS)과 구현체(Swagger)의 차이, YAML·JSON으로 사람과 기계가 함께 읽는 언어 독립적 인터페이스라는 특징, path·components 등 구조를 설명한다.

푸시·문자·이메일·카카오톡 api를 하나로 묶는 퍼사드 통합 과정에서, 수신자를 to·receiver·recipient로, 발송 결과를 result·send result 등 제각각 부르던 용어 파편화가 최대 걸림돌이었다. 스펙 적용 전에 각 상품 용어를 취합·분류해 하나로 통일하는 작업을 선행했다고 공유한다.

api가 한두 개만 늘어도 컨트랙트 파일이 비대해지고 헤더·객체 중복이 심해지는 문제를, JSON reference로 요청·응답 본문과 api 정의를 버전별 파일로 분리·참조해 해결했다. 다만 paths 객체 하위에는 reference를 못 넣어 path item 계층에서 참조하는 우회를 택했다.

언어 독립적이라 자바 Bean Validation 같은 특정 언어 기능을 쓰기 어려운 한계를, x-로 시작하는 확장 필드(x-imports, x-valid 등)로 정의하고 OpenAPI Generator의 Mustache 템플릿을 수정해 검증 애노테이션이 코드로 생성되도록 확장했다.

WebFlux 기반으로 모킹 api를 생성했을 때 Mono·Flux에 걸린 Bean Validation이 동작하지 않는 6.2.0 버그를 추적한 사례다. 자동 생성 코드에 검증 호출이 빠져 있던 원인을 찾아 직접 수정하고 풀리퀘스트로 올려 6.2.1에 반영되게 했다고 밝힌다.

API 컨트랙트로 이해관계자 동의를 얻는 것이 Design First의 핵심임을 재강조하며, OpenAPI가 엔터프라이즈 레벨에선 부족한 부분이 있어 구조 이해와 학습 비용을 감수해야 한다고 정리한다. 무엇보다 마음을 꺾지 않고 꾸준히 실천하는 것이 중요하다고 마무리한다.