자바스크립트, 타입스크립트 테스트기반 문서 자동화 라이브러리, itdoc

itdoc이 해결하는 테스트와 문서의 불일치 문제

자바스크립트와 타입스크립트 개발자들이 가장 흔히 겪는 고충은 테스트와 API 문서 사이의 간극입니다. Express로 간단한 회원가입 엔드포인트를 만들었다고 가정해 볼게요. 먼저 라우터를 정의하고, Jest나 Mocha로 테스트 코드를 작성한 뒤, 또 별도로 Swagger나 Markdown 문서를 손으로 업데이트해야 하죠. 그런데 API 스펙이 바뀌면 테스트는 수정했는데 문서는 그대로 남아 있거나, 반대로 문서는 업데이트했는데 테스트가 실패하는 상황이 반복됩니다. 이런 불일치 때문에 나중에 신규 개발자가 API를 이해할 때 혼란이 생기고, 배포 직전에야 문제를 발견하는 경우도 많아요.

itdoc은 이 과정을 뒤집습니다. 테스트 코드 안에 요청 바디, 응답 상태 코드, 요약 설명까지 모두 정의해 두면, 테스트가 통과하는 순간 Markdown, OpenAPI JSON, HTML 문서가 한 번에 생성돼요. 즉 테스트가 문서의 진실 소스가 되는 구조라서, 테스트만 잘 관리하면 문서는 신경 쓸 필요가 없어집니다. 기존에는 테스트와 문서를 따로 관리하면서 발생하던 휴먼 에러를 근본적으로 없애는 셈이죠.

실제로 팀에서 itdoc을 도입한 뒤로는 API 변경 시 테스트만 수정하면 되고, 문서 업데이트를 깜빡하는 일이 사라졌다고 해요. 특히 프리랜서나 작은 팀처럼 문서 전담 인력이 없는 경우에 체감 효과가 크답니다.

테스트 코드로 문서를 자동 생성하는 방법

itdoc을 쓰려면 먼저 테스트 파일 안에 API 스펙을 선언하는 방식으로 코드를 작성합니다. 예를 들어 signup 엔드포인트라면 POST 메서드, /signup 경로, summary와 description, request body 필드, response status까지 한 곳에 모아 정의해요. 이렇게 작성한 뒤 npm test를 실행하면 Jest가 테스트를 돌리고, 모든 테스트가 통과해야만 문서가 생성됩니다. 테스트가 실패하면 문서 생성 자체가 중단되기 때문에, 문서 품질을 강제로 보장하는 장치가 마련된 셈이죠.

생성되는 결과물은 세 가지예요. 사람이 읽기 좋은 Markdown 파일, OpenAPI 스펙 JSON, 그리고 바로 브라우저에서 볼 수 있는 HTML 문서입니다. HTML은 테이블 형태로 request/response 예시까지 예쁘게 정리돼 있어서, 백엔드 개발자가 아닌 기획자나 디자이너도 쉽게 이해할 수 있어요.

여기서 실전 팁 하나. request body에 민감한 필드가 있다면 테스트 코드에서 실제 값 대신 타입과 설명만 명시하는 게 좋습니다. 그래야 문서에 불필요한 더미 데이터가 노출되지 않거든요. 또 여러 엔드포인트를 한 파일에 모아두면 나중에 유지보수할 때 편리합니다.

LLM으로 테스트까지 자동 생성하는 itdoc generate

테스트 코드조차 작성하기 귀찮은 분들을 위해 itdoc은 LLM 기반 자동 생성 기능도 제공합니다. itdoc generate 명령어를 실행하면 AST 파서가 Express 앱 코드를 분석해서 request/response 부분만 추출한 뒤, GPT가 테스트 코드를 대신 작성해 줍니다. .env 파일에 OpenAI API 키만 넣어두면 되기 때문에 별도 설정이 거의 없어요.

이 기능의 장점은 기존 비즈니스 로직은 건드리지 않고 API 인터페이스만 뽑아낸다는 점입니다. 따라서 생성된 테스트 코드를 그대로 테스트 폴더에 넣고 npm test를 돌리면 동일하게 문서까지 한 번에 나옵니다. 다만 자동 생성된 코드는 한 번 검토해 보는 걸 추천해요. 특히 인증 헤더나 특수한 응답 포맷이 있는 경우에는 살짝 손을 봐야 더 정확한 문서가 만들어지거든요.

결과적으로 itdoc 하나로 테스트 작성 → 문서 자동 생성 → LLM 보조까지 모두 커버할 수 있게 된 셈입니다. 기존에 테스트와 문서를 따로 관리하느라 들이던 시간을 크게 줄일 수 있죠.