레거시 API 문서를 OpenAPI·SDK로 자동 변환하는 SaaS 개발

사이드로 툴 하나를 만들었다. 레거시 API 문서를 OpenAPI / Postman Collection / SDK 형태로 변환해주는 SaaS — 코드명 pdf2api.

왜 이 작업이 필요했나

팀에서 오래된 시스템을 다루다 보면 어김없이 만나는 게 있다. PDF로 배포된 API 명세서, 엑셀로 정리된 파라미터 목록, 위키 어딘가에 박혀 있는 curl 예제들. 개발자 입장에서는 이걸 보고 직접 Postman 컬렉션을 손으로 만들고, 타입 정의를 하나씩 옮겨 적는 작업이 반복된다. 한 번이면 모르겠는데 레거시 시스템이 여러 개면 이 작업만 며칠이 사라진다.

팀장 역할을 하다 보면 이런 종류의 "반복 손노동"이 팀 전체 생산성을 얼마나 갉아먹는지 더 잘 보인다. 개인이 알아서 처리하고 있으니 겉으로 티가 안 날 뿐이지, 집계해보면 꽤 큰 시간이다. 그래서 한번 자동화 도구를 만들어보자는 판단이 섰다.

프로젝트 구조와 초기 설정 파일들

이번 커밋은 프로젝트 초기 뼈대를 잡는 작업이었다. 변경된 파일 목록을 보면 실제 기능 코드보다 설정/문서 파일이 주를 이룬다.

파일 구성만 봐도 이 프로젝트가 AI 에이전트 기반 파이프라인으로 설계됐다는 게 드러난다. AGENTS.md와 CLAUDE.md가 같이 들어간 건 변환 로직 자체를 LLM에 위임하는 구조를 처음부터 명시적으로 가져가겠다는 의도다.

pdf2api/
├── .env.example        ← 환경변수 인터페이스 공개
├── AGENTS.md           ← 에이전트 역할/지침 정의
├── CLAUDE.md           ← Claude 파이프라인 동작 규칙
├── README.md           ← 진입점 문서
└── docs/
    └── C-D-INTEGRATION.md  ← 통합 플로우 명세

이런 초기 커밋에서 내가 중요하게 보는 건 "협업자가 이 레포를 처음 클론했을 때 얼마나 빨리 컨텍스트를 잡을 수 있나"다. README → AGENTS.md → CLAUDE.md 순서로 읽으면 시스템 전체 그림이 잡히게 문서를 배치했다.

.env.example과 AGENTS.md를 같이 넣는 이유

초기 셋업 커밋에서 .env.example을 빠뜨리는 경우가 생각보다 많다. 나중에 "어, 환경변수가 뭐가 필요하죠?"라는 질문이 슬랙에 올라오고, 그때서야 추가하게 된다. 처음부터 .env.example을 커밋에 포함시키는 건 작은 습관이지만 팀 온보딩 비용을 꽤 줄여준다.

AGENTS.md를 별도 파일로 분리한 것도 의도적인 결정이다. AI 에이전트를 쓰는 프로젝트에서 에이전트 지침이 코드나 README에 흩어져 있으면, 나중에 에이전트 동작을 수정하고 싶을 때 어디를 건드려야 하는지 모호해진다. 에이전트 동작 정의를 한 파일로 모아두면:

• 에이전트 동작 변경 시 diff가 명확하게 남음
• 코드리뷰어가 "에이전트 로직이 바뀌었구나"를 즉시 인식
• 여러 에이전트가 붙을 경우 각 역할 분리가 쉬움

회고

솔직히 말하면 이런 류의 SaaS 아이디어는 "있으면 좋겠다"에서 "직접 만든다"로 넘어가는 데 시간이 걸린다. 레거시 문서 변환은 뻔히 보이는 문제인데 왜 아직 제대로 된 도구가 없나 — 그 이유는 케이스마다 문서 형태가 너무 달라서 범용으로 만들기 까다롭기 때문이다. pdf2api가 그 부분을 LLM 파이프라인으로 풀려는 접근이고, 초기 설계 문서들이 이번 커밋에 담겼다.

초기 뼈대 커밋치고 문서가 충실하게 들어간 편이다. docs/C-D-INTEGRATION.md까지 이 시점에 들어간 건, 통합 플로우가 프로젝트 핵심 가치라는 판단이 있었기 때문이다. 나중에 "나중에 문서 쓰지"는 결국 안 쓰게 되는 경우가 많으니까.

다음 커밋에서는 실제 변환 파이프라인 코어가 올라올 예정이다.

🛒 이 글과 어울리는 추천 상품

• 노트북 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.