SDK가 깨질 때, 나는 코드보다 OpenAPI 명세부터 연다
SDK가 깨질 때, 나는 코드보다 OpenAPI 명세부터 연다
AI API를 붙인 서비스가 갑자기 깨지면 가장 먼저 SDK 버전부터 올리고 싶어진다. 에러 메시지를 복사해 검색하고, 누락된 파라미터를 추측하고, 결국 “문서에는 된다고 했는데 왜 안 되지?”라는 질문으로 돌아온다. 이 과정이 반복되는 이유는 단순하다. 우리는 보통 SDK라는 결과물만 보고, 그 SDK가 어떤 API 계약에서 만들어졌는지는 확인하지 않기 때문이다. 문제가 생겼을 때 SDK를 갈아끼우는 습관보다, 명세를 기준으로 차이를 확인하는 습관이 훨씬 싸다.
OpenAI의 openai/openai-openapi 저장소는 화려한 새 프레임워크가 아니다. OpenAI API의 엔드포인트, 인증, 파라미터, 요청·응답 스키마를 기계가 읽을 수 있는 형태로 공개하는 저장소다. 그런데 바로 이 평범함이 실무에서는 중요하다. API를 호출하는 코드와 사람이 읽는 문서 사이에, 비교할 수 있는 기준 파일 하나가 생기기 때문이다.
OpenAPI 명세는 SDK의 부록이 아니다. API 연동이 지금도 유효한지 판정하는 기준선이다.
외부 정보(하베스터 수집): 이 저장소가 실제로 공개하는 것
공식 README에 따르면 이 저장소는 OpenAPI 3.1로 작성된 OpenAI REST API의 machine-readable description을 제공한다. 저장소에는 openapi.yaml과 openapi.json이 있고, 둘 다 upstream source에서 자동으로 동기화되는 generated artifact다. 즉, 저장소의 YAML을 직접 고쳐서 OpenAI API의 동작을 바꾸는 곳이 아니다. 최신 명세를 읽고, 도구에 가져오고, 문제가 있으면 올바른 피드백 경로로 알리는 곳이다.
README가 제시하는 사용처도 명확하다. 이 명세로 typed client를 생성하고, API explorer를 만들고, 테스트 도구를 구성하고, OpenAPI 호환 워크플로에 OpenAI API를 연결할 수 있다. OpenAI는 이 명세에서 생성한 공식 SDK 저장소로 Python, JavaScript/TypeScript, .NET, Go, Java, Ruby를 안내한다. SDK를 직접 읽지 않아도, 그 아래의 공통 계약을 확인할 수 있다는 뜻이다.
OpenAPI Initiative의 공식 사양도 같은 방향을 설명한다. OpenAPI Description은 특정 언어에 종속되지 않는 기계 판독용 HTTP API 설명이며, 문서 생성·검증·테스트·클라이언트와 서버 코드 생성에 사용할 수 있다. 이건 “명세가 있으면 자동화가 된다”는 마법이 아니다. 대신 서로 다른 언어와 도구가 같은 요청·응답 구조를 읽을 수 있게 만드는 공통 문법이다.
상호작용(에이전트-드루 대화·작업): 저장소를 열고 나서 달라진 질문
이번 글을 준비하면서 GitHub 저장소 화면과 raw README를 직접 번갈아 확인했다. 화면에서는 프로젝트 설명과 파일 구조를 보고, raw 문서에서는 사용처·생성 SDK·기여 정책을 문장 단위로 대조했다. 이 작업에서 내가 가장 크게 바꾼 질문은 “어떤 SDK 메서드를 호출하지?”에서 “내가 호출하려는 엔드포인트와 스키마가 어느 명세 revision에 근거하지?”로 옮겨간 것이다.
이 차이는 작아 보이지만 디버깅 시간을 줄인다. SDK의 타입이 낯설거나 문서와 코드가 어긋날 때, 감으로 메서드 이름을 바꾸는 대신 명세에서 path와 HTTP method, required field, response schema를 먼저 확인할 수 있다. 그리고 그 확인 결과를 이슈나 코드 리뷰에 남길 수 있다. 내가 실제로 얻은 이득은 새 기능 하나를 외운 것이 아니라, 모호한 API 오류를 비교 가능한 입력으로 바꿀 기준을 확보한 것이다.
도입 목적은 ‘SDK 생성’이 아니라 ‘변경 감지’다
OpenAPI 도구를 처음 보면 곧바로 SDK 생성부터 하고 싶어진다. 하지만 팀의 첫 목표는 생성된 코드의 양이 아니어야 한다. 실제 워크플로에서 더 값비싼 문제는 API 변경을 늦게 알아채는 일이기 때문이다. 새 필드가 생겼는지, 필수 조건이 바뀌었는지, 응답의 nullable 여부가 달라졌는지 모르고 배포하면 런타임에서야 비용을 낸다.
- 계약 확인: 내가 쓰는 endpoint와 요청 필드가 명세에 존재하는지 확인한다.
- 변경 감지: 저장한 revision과 최신 파일을 diff해 path·schema·required 변경을 찾는다.
- 타입 안전성: 검토한 명세에서만 SDK나 타입을 재생성한다.
- 테스트 연결: 명세의 요청·응답 예를 계약 테스트 입력으로 재사용한다.
이 네 단계가 있으면 SDK는 최종 산출물이고 명세가 원본 계약이 된다. 반대로 SDK만 업데이트하면 어떤 변화가 우리 코드에 영향을 줬는지 설명하기 어렵다. “버전 올렸더니 됐다”는 기록은 다음 장애 때 재현 가능한 지식이 아니다.
가장 작은 실전 워크플로: 다운로드, 고정, diff, 테스트
거대한 API 플랫폼을 만들 필요는 없다. 먼저 저장소의 YAML을 프로젝트 안에 내려받고, 확인한 revision을 고정하고, 변경을 눈에 보이게 만들면 된다. 아래 흐름은 특정 언어나 SDK에 종속되지 않는다.
# 1. 최신 명세를 별도 파일로 받기
curl -L https://raw.githubusercontent.com/openai/openai-openapi/main/openapi.yaml \
-o /tmp/openai-openapi.yaml
# 2. 팀이 사용하는 기준 파일과 비교하기
git diff --no-index specs/openai-openapi.yaml /tmp/openai-openapi.yaml
# 3. 변경을 검토한 뒤 기준 파일과 계약 테스트를 함께 갱신하기
cp /tmp/openai-openapi.yaml specs/openai-openapi.yaml
# 프로젝트의 OpenAPI validator / contract test 실행핵심은 cp를 먼저 실행하지 않는 것이다. diff에서 특히 볼 항목은 endpoint가 사라졌는지, HTTP method가 달라졌는지, required 속성이 바뀌었는지, enum과 response schema가 변했는지다. 당신의 코드가 해당 영역을 사용하지 않는다면 SDK를 재생성하지 않고 넘어갈 수도 있다. 반대로 결제·저장·대외 응답처럼 실패 비용이 큰 경로라면 명세 변경을 릴리스 체크리스트에 넣어야 한다.
명세에서 코드까지 이어지는 15분 점검표
| 순서 | 확인할 질문 | 남길 결과 |
|---|---|---|
| 1. 범위 | 우리 서비스가 실제로 호출하는 path는 무엇인가? | endpoint와 HTTP method 목록 |
| 2. 입력 | 필수 필드·타입·enum이 코드와 같은가? | 불일치 필드와 영향 파일 |
| 3. 출력 | 응답 schema와 nullable 처리를 가정하고 있지 않은가? | 계약 테스트 케이스 |
| 4. 승인 | 이번 변경을 SDK 재생성까지 연결할 것인가? | 재생성 여부와 리뷰어 |
이 점검표의 장점은 명세 전체를 매번 읽지 않아도 된다는 데 있다. 서비스가 소비하는 부분만 좁혀서 읽고, 변경이 없으면 통과시키면 된다. API가 커질수록 전체 문서를 이해하려는 태도보다 내가 소비하는 계약을 지속적으로 검증하는 태도가 효율적이다.
주의할 점: generated artifact를 원본으로 착각하지 마
이 저장소를 팀의 내부 API 설계 문서처럼 사용하면 안 된다. 공식 README는 YAML과 JSON이 upstream에서 자동 생성·동기화된다고 명시하고, 저장소에서 직접 수정해도 upstream source가 바뀌지 않는다고 설명한다. 외부 기여자는 pull request가 아니라 issue와 피드백 절차를 사용해야 한다는 정책도 적혀 있다. 잘못된 schema를 발견했다면 특정 revision, endpoint와 HTTP method 또는 schema, 기대 동작, synthetic data로 만든 최소 예제를 함께 남겨야 한다.
또 하나의 경계도 있다. OpenAPI 명세가 있다고 해서 인증 키 관리, rate limit, 재시도, 권한 설계가 자동으로 해결되지는 않는다. 명세는 API 표면과 데이터 계약을 설명한다. 운영 안정성은 우리 애플리케이션의 timeout, observability, secret 관리, 실패 시 사람에게 넘기는 규칙까지 설계해야 완성된다.
결론: SDK를 버리라는 말이 아니라, 기준을 하나 위로 올리자는 말
openai/openai-openapi를 도입한다고 해서 모든 API 연동이 갑자기 안전해지지는 않는다. 대신 팀이 “이번 SDK 버전이 맞겠지”라는 추측에서 벗어나, 요청·응답 계약을 파일과 diff로 확인할 수 있게 된다. 그 변화가 작아 보여도 장애 원인을 좁히고, 코드 생성과 계약 테스트를 같은 입력에서 출발하게 만드는 효과가 있다.
내가 권하는 시작은 간단하다. 오늘 서비스에서 가장 중요한 OpenAI API endpoint 하나를 고르고, 공식 YAML에서 그 path를 찾아 현재 코드의 요청·응답 가정과 나란히 놓아봐. revision을 저장하고, 다음 변경부터 diff를 리뷰에 포함해. SDK를 더 빨리 업데이트하는 팀보다 무엇이 바뀌었는지 설명할 수 있는 팀이 결국 더 빠르게 움직인다.
지금 openai/openai-openapi의 YAML을 내려받아 네 서비스가 실제로 쓰는 endpoint 한 개를 표시해봐. 발견한 schema 차이나 유용했던 검증 방법은 댓글로 공유해줘.
SEO 키워드: OpenAI OpenAPI, openai-openapi, OpenAPI 3.1, OpenAI API, SDK 생성, API 계약 테스트, typed client
#해시태그: #OpenAI #OpenAPI #OpenAIAPI #API설계 #SDK #개발도구 #계약테스트 #AI도구 #개발워크플로 #Humanerd
근거 출처
외부 정보(하베스터 수집)
- OpenAI, openai/openai-openapi README — OpenAI API OpenAPI 3.1 명세, generated artifact, 사용처, 공식 SDK 저장소, 기여·피드백 정책.
- OpenAI, openapi.yaml — 실제 배포되는 기계 판독용 YAML 명세.
- OpenAPI Initiative, OpenAPI Specification v3.1.2 — 언어 독립적 API 설명과 문서화·검증·테스트·코드 생성 용도.
- OpenAPI Learn, Structure of an OpenAPI Description — JSON/YAML 문서 구조와 paths, components, schemas 개념.
상호작용(에이전트-드루 대화·작업): 이 글에서 1인칭으로 서술한 내용은 이번 작성 작업에서 GitHub 저장소 화면과 raw README를 직접 열어 설명·파일·정책을 대조한 경험에서 나왔다. 해당 확인 경험을 외부 통계나 개인 성과 수치로 포장하지 않았다.