API 문서를 에이전트가 직접 읽게 만든다

코딩 에이전트에게 API를 붙일 때마다 스웨거(Swagger) 문서를 통째로 복사해 프롬프트에 붙여 넣던 방식이 바뀌고 있다. 네스트JS(NestJS) 문서화 툴체인 네스트제이에스독파이(nestjs-docfy)는 프로젝트의 OpenAPI 명세를 MCP 도구로 노출해 클로드(Claude)나 커서(Cursor) 같은 에이전트가 API를 직접 조회하게 만든다. 최신 버전은 0.16.1이며 MIT 라이선스다.

무슨 일인가

이 도구의 출발점은 에이전트가 아니라 지저분한 컨트롤러 코드였다. 네스트JS에서 문서화 데코레이터를 붙이다 보면 라우트 코드가 설명과 응답 예시에 파묻힌다. 독파이는 그 문서를 동반 파일로 분리한다. 컨트롤러 파일 옆에 같은 이름의 문서 파일을 두는 규약으로, 테스트 파일을 짝지어 두는 기존 관행과 동일한 방식이다. 부팅 시점에 규약을 따라 문서 파일을 찾아 컨트롤러 메서드에 메타데이터를 심으므로, 최종적으로 생성되는 OpenAPI 결과물은 데코레이터를 코드에 직접 쓴 것과 완전히 같다. 런타임 프록시나 원숭이 패치 없이 타이밍과 메타데이터만 이용하며, 요청마다 발생하는 추가 비용은 없다고 설명한다.

핵심 짚어보기

주목할 부분은 문서를 사람이 아니라 기계가 소비하도록 설계한 지점이다. 독파이MCP(docfy-mcp)는 OpenAPI 명세를 MCP 도구 묶음으로 열어 에이전트가 JSON을 복사해 붙여 넣지 않고도 API를 질의하게 한다. 제공되는 기능은 네 가지다. 엔드포인트 목록 조회와 개별 조회로 API를 탐색하고, 명세 검사 도구가 요약과 설명, 태그, 오류 응답 누락을 배포 전에 잡아낸다. 두 명세를 비교해 호환성을 깨는 변경과 단순 정보성 변경을 구분하는 도구, 실제 서버 응답이 선언된 스키마와 맞는지 검증하는 계약 테스트 도구도 들어 있다. 실행 중인 서버를 가리키면 별도 설정 없이 동작하고 정적 명세 파일을 지정할 수도 있다.

CLI는 지속적 통합 단계의 관문 역할을 한다. 생성과 검사, 최소 커버리지 지정, 린트, 명세 패치 명령을 제공해 문서가 코드와 어긋나는 순간 빌드를 실패시킨다. 몇 달 뒤에 발견하는 대신 그 자리에서 막는 구조다. 인터페이스와 유효성 검증 클래스, 상태 코드 데코레이터에서 스키마를 자동으로 추론하므로 별도 표기를 덧붙이는 부담도 줄였다. 함께 제공되는 뷰어는 엔드포인트마다 AI용 복사 버튼을 두는데, 참조가 얽힌 원시 JSON이 아니라 언어 모델이 바로 쓸 수 있게 정리된 요약을 내놓는 점이 차이다. 단순 프로젝트는 물론 Nx 워크스페이스와 모노레포 구조도 자동 인식하며, 초기화 명령 한 번으로 모듈 배선과 문서 생성이 끝난다고 소개한다.

1인기업 실전 적용 포인트

• 자체 API를 운영한다면 명세를 MCP로 노출하는 작업을 먼저 하라. 에이전트에게 매번 문서를 붙여 넣는 시간이 사라지고, 붙여 넣기 누락에서 오는 잘못된 코드 생성도 줄어든다.
• 계약 테스트 도구는 외주나 협업 상황에서 특히 값이 크다. 상대가 넘긴 응답이 합의한 스키마와 다른지를 에이전트가 스스로 확인하게 만들면 검수 시간이 통째로 줄어든다.
• 명세 비교 기능은 자체 서비스 버전 관리에 그대로 쓸 수 있다. 배포 전에 이전 명세와 비교해 호환성을 깨는 변경만 뽑아 배포 노트에 넣는 루틴을 자동화한다.
• 문서 커버리지 하한선을 지속적 통합에 걸어 두면 혼자 개발하면서도 문서가 썩는 속도를 늦출 수 있다. 사람이 자기 자신을 검토하는 대신 빌드가 검토하게 만드는 방식이다.

전망과 주의점

이 도구는 네스트JS 생태계에 묶여 있어 다른 프레임워크 사용자에게는 곧바로 적용되지 않는다. 그러나 방향은 프레임워크를 가리지 않는다. 문서를 사람이 읽는 결과물이 아니라 에이전트가 호출하는 인터페이스로 다시 정의하는 흐름이며, MCP는 그 인터페이스의 공통 규격 자리를 노리고 있다. 1인기업이라면 여기서 얻을 실익이 분명하다. 문서 작성은 늘 미뤄지는 일이었지만, 그 문서가 곧 에이전트의 작업 정확도로 되돌아온다면 우선순위가 달라진다.

출처: Nest Docfy 공식 사이트 (https://www.nestdocfy.com/)