API 개발을 할 때마다 "OpenAPI (Swagger) 정의서, 또 직접 써야 하나……"라며 한숨을 쉬고 계시지는 않나요? 엔드포인트(Endpoint)가 늘어날수록 yaml의 기술량도 방대해지며, 코드와의 정합성을 유지하는 것도 큰 일입니다. 이 기사에서는 Claude Code를 사용하여 OpenAPI 정의를 효율적으로 만드는 방법을 구체적인 프롬프트(Prompt) 예시와 검증 절차와 함께 해설합니다. 다 읽을 때쯤에는 수기로 작성하는 것보다 몇 배나 빠른 속도로 문서를 정비할 수 있게 될 것입니다.

결론부터 말씀드리면, Claude Code는 OpenAPI 정의 작성에 있어 강력한 파트너가 됩니다. 이미 존재하는 컨트롤러(Controller)나 라우팅(Routing) 코드를 읽히게 하여 사양서를 역생성할 수도 있고, 반대로 API를 아직 만들지 않은 단계에서 "이런 API를 만들고 싶다"라고 대화하며 제로 베이스에서 yaml을 설계하는 것도 가능합니다. 수기로 작성하며 고민하고 계신가요? 그 고민은 프롬프트 하나로 해결되는 경우가 많습니다.

이유는 크게 두 가지입니다. 하나는 Claude Code가 프로젝트 전체의 코드를 읽을 수 있기 때문에, 컨트롤러의 메서드명(Method name)·인수(Argument)·반환값(Return value)의 타입으로부터 엔드포인트의 사양을 추측할 수 있다는 점입니다. 또 다른 하나는 CLAUDE.md에 출력 규칙(버전, 명명 규칙, 태그 지정 방침 등)을 적어두면 매번 동일한 포맷으로 yaml을 생성해 준다는 점입니다. 저는 이 두 가지를 조합함으로써 사양서의 편차가 상당히 줄어들었다고 느꼈습니다.

실제로 OpenAPI를 만드는 상황은 프로젝트의 상태에 따라 달라집니다. 대표적인 3가지 패턴을 표로 정리했습니다.

❌ 갑자기 "OpenAPI 만들어줘"라고만 지시하기

✅ "대상 디렉토리", "OpenAPI 버전", "인증 방식 (Bearer 등)"을 처음에 전달하기

◎ 추가로 "응답 예시 (example)도 포함해서"라고 명시하기

이 세 줄만으로도 생성되는 yaml의 정밀도는 상당히 달라집니다.

먼저 "이 리포지토리의 API 라우팅 부분을 파악해줘"라고 전달하여 엔드포인트 목록을 대략적으로 인식시킵니다. Express, FastAPI, Rails, Laravel 등 프레임워크가 무엇이든, 라우팅 정의나 컨트롤러 파일을 기점으로 읽히게 하는 것이 요령입니다.

프로젝트 루트의 CLAUDE.md에 다음과 같은 규칙을 적어두면, 매번 유사한 포맷으로 OpenAPI를 출력하게 됩니다.

"src/api/ 하위의 컨트롤러를 읽어서 openapi.yaml을 생성해 주세요. CLAUDE.md의 규칙을 따라주세요"와 같이 대상 범위와 규칙 참조를 명시하여 의뢰합니다.

생성된 yaml은 반드시 구문 체크(Syntax check)를 수행합시다. Claude Code에게 "npx @redocly/cli lint openapi.yaml을 실행해서 에러가 있으면 수정해줘"라고 이어서 의뢰하면, 검증부터 수정까지 한 번에 처리해 줍니다.

반복적으로 OpenAPI를 업데이트하는 프로젝트라면, 파일 편집 후에 자동으로 Lint를 실행하는 Hook을 구성해 두는 것도 추천합니다. 수동 체크를 잊을 리스크를 줄일 수 있습니다.

여기까지의 절차를 밟더라도 처음부터 완벽한 OpenAPI가 나온다는 보장은 없습니다. 제가 실제로 시도하며 깨달은, 정밀도를 높이기 위한 포인트를 심층 분석합니다.

저는 처음에 API 전체를 한 번에 OpenAPI화하려고 했다가, 결국 검토하는 데 시간이 많이 걸리고 말았습니다. 지금은 "먼저 users 관련만 생성 → 확인 → orders 추가"와 같이 리소스 단위로 조금씩 진행하는 방법으로 바꾸었습니다. 이 방법이 결과적으로 재작업이 적고 납득할 수 있는 사양서로 완성된다고 느낍니다.

OpenAPI 정의와 코드 구현이 어긋나 있지 않은지 Claude Code에게 "이 yaml과 구현 코드를 비교해서 모순점이 있다면 알려줘"라고 묻는 것도 유효합니다. 문서만 오래된 상태로 남게 되는, Qiita에서도 자주 보이는 고민을 여기서 예방할 수 있습니다.

• ✅ Claude Code는 OpenAPI의 「역생성 (Reverse Engineering)", 「제로 베이스 설계 (Design from scratch)", 「스키마 퍼스트 (Schema-first)」 모두에 대응할 수 있음
• ✅ CLAUDE.md에 출력 규칙을 작성해 두면, 생성 시의 편차를 줄일 수 있음
• ◎ 생성 후에는 반드시 swagger-cli나 Redocly CLI로 구문 검증 (Syntax Validation)을 수행할 것
• ✅ 한꺼번에 전체를 만들지 않고, 리소스 단위로 확인하며 진행하는 것이 안전함
• ◎ 코드와 OpenAPI의 정합성 체크 (Consistency Check)도 Claude Code에게 맡길 수 있음