API 응답에서 타입 만들기 — JSON을 코드로 받아 적는 법

새 API를 붙일 때마다 반복되는 그 작업 — 응답 JSON을 한 줄씩 보며 interface를 받아 적기. 필드 30개짜리 응답이면 10분이 사라지고, 오타 하나가 런타임 버그가 됩니다. 기계적으로 끝내는 법과, 자동 변환이 못 잡는 것들을 정리합니다.

왜 손으로 쓰면 안 되나

• 오타는 컴파일을 통과합니다 — userName을 username으로 적으면, 에러 없이 조용히 undefined가 흐릅니다. 가장 잡기 어려운 종류의 버그입니다.
• 누락도 통과합니다 — 안 적은 필드는 "없는 것"이 될 뿐, 경고가 없습니다.
• 시간이 아깝습니다 — 받아 적기는 기계가 사람보다 정확하고 빠른 대표적인 작업입니다.

자동 변환 1분 컷

1. API의 실제 응답 JSON을 복사합니다 — 문서 예시보다 실제 응답이 정확합니다.
2. JSON → 타입 변환기에 붙여 넣고 언어(TypeScript·Python·Go)를 고릅니다.
3. 생성된 타입 코드를 복사해 프로젝트에 붙입니다 — 중첩 객체는 자동으로 별도 타입으로 분리됩니다.

변환 후 다듬을 것 세 가지

자동 변환은 샘플에 보이는 것만 압니다. 다음 세 가지는 사람이 마무리해야 합니다.

• null·빈 배열 필드 — 타입을 확정할 수 없어 any(TS)·Any(Python)·interface{}(Go)로 나옵니다. 실제 타입을 명시하세요.
• 선택(optional) 필드 — 샘플에 우연히 없던 필드는 타입에도 없습니다. API 문서를 보고 ?를 붙이거나 필드를 추가하세요.
• 자동 이름 — 중첩 타입은 키 이름으로 자동 명명됩니다(DataItem 등). 도메인에 맞는 이름으로 바꾸면 가독성이 올라갑니다.

언어별 출력의 모양

• TypeScript — interface. 프런트엔드에서 응답 타입으로 바로 사용.
• Python — @dataclass 클래스. 타입 힌트와 함께 생성됩니다.
• Go — JSON 태그(`json:"..."`)가 달린 struct. 언마샬링에 바로 사용.
• 자바가 필요하면 JSON → Java DTO 도구가 따로 있습니다.