코드에서 API 명세 표 뽑기

엔드포인트 1개가 나왔고, 코드에 타입이 없는 항목은 (추정), 값이 없는 응답 필드 3개는 "코드에서 확인 불가"로 표시됐다. 인증이 걸린 엔드포인트라는 표시도 붙었다.

POST /api/orders — 주문을 만든다. 인증 필요(auth 미들웨어)

오류는 400 하나만 적혔고 인증 실패 응답은 확인 불가로 남았다. 미들웨어 코드도 함께 넣으면 그 칸이 채워진다.

API 문서 작성을 ChatGPT에 맡길 때 가장 자주 나는 사고는, 코드에 없는 파라미터가 표에 들어가는 것입니다. 코드만 던져 주면 AI는 흔한 REST 관례를 떠올려 page, limit, sort 같은 항목을 그럴듯하게 채웁니다. 그 문서를 보고 개발한 사람은 없는 파라미터를 실어 호출하다 400을 받습니다.

과제 문단이 "코드에 실제로 적혀 있는 엔드포인트만"이라고 못 박는 이유가 여기 있습니다. 뽑을 항목을 경로·메서드·요청·응답·오류로 나열한 것도 같은 목적입니다. 목록을 주지 않으면 AI는 경로와 한 줄 설명만 적고, 정작 필요한 요청 본문 구조를 건너뜁니다. 오류 응답을 항목에 넣어 둔 것도 같은 이유입니다. 성공 응답만 적힌 문서는 화면을 만들 때 거의 도움이 되지 않습니다.

맨 앞에서 프레임워크를 밝히는 것은 라우팅 규칙과 데코레이터가 제품마다 다르기 때문입니다. @RequestParam 이 쿼리인지 본문인지, req.params 가 경로 변수인지는 프레임워크를 알아야 판단됩니다. 형식에 "위치(경로/쿼리/본문)" 열을 넣은 것도 이 구분을 표에 남겨 두기 위해서입니다.

제약의 "코드에서 확인 불가"와 (추정) 표시는 API 명세서 자동 생성에 꼭 필요한 안전장치입니다. 빈칸을 두면 AI는 채우려 들지만, 적을 말이 정해져 있으면 모르는 것을 모른다고 적습니다. 코드를 """ 로 감싼 것은 주석에 섞인 "TODO: 이 부분은 무시" 같은 문장이 지시로 읽히지 않게 하기 위해서입니다.

표는 나오지만 코드에 없는 page·limit 같은 파라미터가 섞이고, 필수 여부와 파라미터 위치가 빠져 그대로 쓰면 호출이 실패합니다. 오류 응답은 아예 빠지는 일이 많아, 결국 프런트엔드가 실패 케이스를 하나씩 물어보게 됩니다. 여러 엔드포인트를 한 번에 붙이면 형식도 제각각이라 나중에 문서를 이어 붙이기도 어렵습니다.