API 문서를 위한 8가지 AI 도구를 테스트했습니다 — 단 2개만이 제 워크플로우에서 살아남았습니다

저는 지난 3개월 동안 분당 15,000개의 요청을 처리하는 REST API를 재구축하는 데 시간을 보냈습니다. 코드는 탄탄했습니다. 하지만 문서는 엉망진창이었습니다.

저희 팀은 47개의 엔드포인트(endpoints), 12개의 웹훅(webhook) 이벤트, 그리고 6개의 인증 흐름(authentication flows)을 세 가지 서로 다른 형식으로 문서화해 두었습니다. Swagger 명세(specs)는 4개월이나 지난 상태였습니다. Postman 컬렉션(collections)은 서로 충돌하는 두 가지 버전으로 존재했습니다. 그리고 내부 Notion 페이지는요? 누군가 속도 제한(rate limits)을 버스트 동작(burst behavior)에 대한 언급 없이 "초당 약 100회 요청"이라고 문서화해 두었다고만 말씀드리겠습니다.

저는 이 문제에 AI를 투입하기로 결정했습니다. 이 난장판을 해결하기 위해 8가지의 서로 다른 도구를 테스트했을 때 어떤 일이 일어났는지 소개합니다.

기준이 되는 문제점 (The Baseline Problem)

도구들에 대해 설명하기 전에, 제가 처한 상황은 다음과 같습니다:

지표 (Metric)	AI 도입 전
문서 정확도 (Documentation accuracy)	62%
...

저에게는 제 코드베이스(codebase)를 읽고, 기존 문서를 이해하며, 정확하고 일관된 결과물을 생성할 수 있는 무언가가 필요했습니다. 환각(hallucinations)도 없어야 하고, 지어낸 파라미터(parameters)도 없어야 하며, "엔터프라이즈 플랜 사용을 고려해보세요"와 같은 업셀링(upsells)도 없어야 했습니다.

후보군 (The Candidates)

저는 세 가지 실제 엔드포인트를 대상으로 각 도구를 테스트했습니다: 사용자 생성을 위한 간단한 POST 요청, 8개의 선택적 파라미터가 포함된 복잡한 웹훅(webhook) 설정, 그리고 리프레시 토큰 로테이션(refresh token rotation)이 포함된 OAuth 흐름입니다.

도구 1: DocuGen AI (실패)

첫 번째는 DocuGen AI였습니다. 이 도구는 "코드로부터 아름다운 문서를 자동으로 생성"해 준다고 약속했습니다. 저는 제 리포지토리(repository)를 지정하고 12,000줄의 TypeScript를 처리하기 위해 20분 동안 기다렸습니다.

결과물은 깔끔해 보였습니다. 하지만 내용은 틀렸습니다.

이 도구는 더 이상 사용되지 않는(deprecated) 엔드포인트를 주요 메서드(method)로 문서화했습니다. X-Idempotency-Key 헤더(header)는 완전히 누락되었습니다. 그리고 OAuth 흐름의 경우, 제가 2023년에 제거한 password grant type을 설명했습니다.

정확도 측면에서 실패했습니다. 점수: 2/10.

도구 2: SwaggerBot (실패)

SwaggerBot은 API 트래픽 로그(traffic logs)를 가져와 OpenAPI 3.1 명세(specs)를 생성합니다. 저는 프로덕션 트래픽 데이터가 있었기 때문에 이 방식이 완벽하게 들렸습니다.

그것은 관찰된 엔드포인트(endpoints)에 대해 87%의 정확도로 명세(spec)를 생성했습니다. 문제는 무엇이었을까요? 그것은 제 47개의 엔드포인트 중 34개만 확인했습니다. 트래픽 양이 적은 엔드포인트들은 완전히 누락되었습니다. 그리고 웹훅(webhook) 이벤트는 서버에서 시작되는 것이기 때문에 그것을 전혀 처리할 수 없었습니다.

탐색(discovery)에는 좋지만, 완전성(completeness) 측면에서는 나쁩니다. 점수: 5/10.

도구 3: CodeDoc AI (실패)

이 도구는 소스 코드를 읽고 인라인(inline)으로 문서를 생성합니다. 함수 시그니처(function signatures)를 이해하기 위해 AST 파싱(AST parsing)을 사용합니다.

저의 간단한 POST 엔드포인트에 대해서는 완벽한 JSDoc 주석을 생성했습니다. 하지만 복잡한 웹훅에 대해서는 어땠을까요? 제가 가진 파라미터(parameters)는 8개뿐이었는데 14개를 생성했습니다. AI가 "일반적인 패턴에 기반한 선택적 필드(optional fields)"를 추론하여 존재하지 않는 3개를 만들어낸 것입니다.

점수: 4/10. 환각(Hallucinations)은 결격 사유입니다.

도구 4: DocuWriter (실패)

DocuWriter는 Postman 컬렉션(collections)을 문서로 변환합니다. 저에게는 두 개의 컬렉션이 있습니다. 이것은 충돌하는 예시들이 포함된 하나의 문서로 그것들을 병합해 버렸습니다.

가장 최악인 부분은 응답 예시에서 속도 제한(rate limit) 헤더를 조용히 누락시켰다는 점입니다. 제 API는 모든 응답에서 X-RateLimit-Remaining과 X-RateLimit-Reset을 반환합니다. 하지만 사라졌습니다. 속도 제한에 대한 문서가 전혀 없었습니다.

점수: 3/10.

도구 5: APIDoc Studio (실패)

이 도구는 코드 읽기, 트래픽 모니터링, Postman 파싱, 문서 생성까지 모든 것을 하려고 시도했습니다. 하지만 이 네 가지 모두에서 실패했습니다.

UI는 세 번이나 충돌했습니다. 생성된 마크다운(markdown)은 링크가 깨져 있었습니다. 그리고 특정 섹션을 다시 생성해 달라고 요청했을 때, 45초가 걸렸음에도 똑같이 깨진 결과물을 반환했습니다.

점수: 1/10. 월 49달러의 구독료가 후회됩니다.

도구 6: Mintlify + AI (실패)

Mintlify의 기본 제품은 탄탄합니다. 그들의 AI 기능은 2025년 말에 출시되었습니다. 저는 기대를 품었습니다.

AI는 간단한 엔드포인트에 대해 괜찮은 설명을 생성했습니다. 하지만 제 웹훅 설정에 있는 중첩된 객체 파라미터(nested object parameters)는 처리하지 못했습니다. 모든 속성(properties)을 하나의 리스트로 평탄화(flattened)하여 부모-자식 관계(parent-child relationships)를 잃어버렸습니다.

점수: 5/10. 기반은 좋지만, AI가 약합니다.

도구 7: ReadMe.io AI (생존)

ReadMe.io는 2026년 1월에 AI 기능을 추가했습니다. 이들의 접근 방식은 다릅니다. 이들은 AI를 자동 생성기가 아닌, 글쓰기 보조 도구 (writing assistant)로 사용합니다.

제가 기본 구조를 작성하면, AI가 개선 사항을 제안했습니다. 제가 놓친 불일치 사항을 잡아냈습니다. 6가지 언어로 예제 코드 (example code)를 생성했습니다. 그리고 제가 엔드포인트 (endpoint)를 업데이트했을 때, 이전 시그니처 (signature)를 참조하고 있는 다른 3개의 페이지를 강조 표시해 주었습니다.

2주간의 작업 결과, 제 문서의 정확도는 62%에서 94%로 올라갔습니다. 지원 티켓 (support tickets)은 월 89건으로 감소했습니다. AI 덕분에 작성 및 교정 (proofreading) 작업에서 매주 약 8시간을 절약했습니다.

점수: 8/10. 여전히 인간의 감독 (human oversight)이 필요합니다.

도구 8: Speakeasy (생존)

Speakeasy는 문서도 함께 생성하는 코드 생성 (code generation) 도구입니다. 제가 (ReadMe로 수정한 후) OpenAPI 스펙 (spec)을 지정하자, Python, JavaScript, Go, Java용 SDK를 생성했습니다.

이 도구가 생성한 문서는 구조적으로 정확했습니다. SDK를 생성한 것과 동일한 스펙에서 나왔기 때문입니다. 불일치 (divergence)가 발생할 가능성이 없습니다. 생성된 코드 예제들은 첫 시도에 바로 작동했습니다.

설정에는 3시간이 걸렸습니다. 유지보수 (maintenance)는 거의 제로에 가깝습니다. 제가 스펙을 업데이트할 때마다 모든 것이 다시 생성됩니다.

점수: 9/10. 서사적 문서 (narrative documentation)를 잘 다루지 못한다는 점 때문에 1점을 감점했습니다.

작동하는 워크플로우 (The Workflow That Works)

💡 추가 읽을거리: 저는 AI 자동화와 오픈 소스 (open-source) 도구를 실험합니다. Pi Stack에서 더 많은 가이드를 찾아보세요.

💰 스마트한 베팅을 원하시나요? 저는 선거 결과부터 기술 트렌드까지 모든 것에 베팅하기 위해 세계 최대의 예측 시장 (prediction market) 플랫폼인 Polymarket을 사용해 왔습니다. 실제 돈, 실제 확률, 실제 수익이 오갑니다. 크립토 카지노와 달리, Polymarket은 대중보다 더 많은 정보를 가지고 있는 것이 우위 (edge)가 되는 합법적인 정보 시장입니다. 저는 AI 규제 타임라인과 크립토 ETF 승인을 예측하여 꽤 괜찮은 수익을 올렸습니다. 제 추천 링크로 가입하고 거래를 시작하세요: Polymarket.com