API 문서 프롬프트가 해결하는 문제는 엔드포인트는 다 만들었는데 문서 작성이 계속 미뤄지는 상황입니다. 코드는 이미 운영 중인데 호출하는 쪽은 소스를 읽으며 파라미터를 추측해야 하고, 연동할 때마다 타입, 필수 여부, 오류 코드를 다시 묻습니다. 아래 프롬프트를 복사해 엔드포인트 코드나 정의를 붙이고 독자와 출력 형식을 채우면 AI가 용도, 파라미터 표, 요청 예시, 응답 예시, 오류 코드 설명을 호출자가 실제로 찾아보는 순서대로 출력합니다. 필드만 확인하면 바로 공유할 수 있습니다.
이 프롬프트가 맞는 상황
이미 코드가 있고 문서만 없는 엔드포인트에 맞습니다. 프런트엔드나 외부 파트너에게 넘기기 직전의 백엔드 엔드포인트, 오래된 프로젝트의 문서 보완, 신규 입사자가 인수 전에 여러 엔드포인트의 입력과 출력을 파악하는 경우가 대표적입니다. 업무 규칙까지 대신 확인해 주지는 않습니다. 코드에 명시되지 않은 검증 로직, 권한 요건, 제한 수치는 지어내지 말고 미확인으로 표시하게 해야 합니다. 필드가 아직 자주 바뀐다면 먼저 파라미터 표만 생성하고, 필드가 안정된 뒤에 예시를 붙이는 편이 문서가 금방 낡는 일을 막아 줍니다.
그대로 복사할 수 있는 프롬프트 본문
당신은 API 문서 에디터입니다. 제가 붙이는 엔드포인트 코드나 정의를 바탕으로, 호출자가 그대로 연동 작업을 진행할 수 있는 문서를 작성하세요.
엔드포인트 코드 또는 정의: {{엔드포인트코드}}
문서 독자: {{독자}}
인증 방식: {{인증방식}}
기본 주소 설명: {{기본주소}}
출력 요구사항:
1. 먼저 이 엔드포인트가 무엇을 하는지, 언제 호출하는지를 두 문장으로 쓰세요. 코드를 되풀이하지 마세요.
2. 이어서 파라미터 표를 만드세요. 각 파라미터마다 이름, 위치(경로, 쿼리, 헤더, 본문), 타입, 필수 여부, 의미를 쓰세요. 코드에서 확인할 수 없는 의미는 미확인으로 표시하고 추측하지 마세요.
3. 완전한 요청 예시와 성공 응답 예시를 하나씩 제시하세요. 필드명과 타입은 코드와 완전히 일치해야 하고, 예시 값은 마스킹된 가짜 데이터를 쓰세요.
4. 오류 코드 설명을 따로 정리하세요. 코드가 실제로 발생시키는 오류만 나열하고, 발생 조건과 호출자가 해야 할 대응을 쓰세요. 코드에 없는 오류 코드는 추가하지 마세요.
5. 마지막에 미확인 목록을 만드세요. 코드에 명시되지 않은 검증 규칙, 권한 요건, 경계 상황을 항목별로 나열하고, 제가 확인한 뒤에 본문에 넣으세요.바꿔 넣을 변수 채우는 법
- 엔드포인트 코드: 함수 이름만 붙이지 말고 처리 함수, 라우트 정의, 관련 요청과 응답 구조체까지 붙이세요. 맥락이 완전할수록 파라미터 표의 미확인 항목이 줄어듭니다.
- 문서 독자: 사내 프런트엔드인지, 외부 파트너인지, 신규 백엔드 개발자인지 쓰세요. 독자가 다르면 예시의 상세 수준과 업무 용어 설명 필요성이 크게 달라집니다.
- 인증 방식: 토큰, 서명, 게이트웨이 통합 인증 중 무엇인지 밝히세요. 인증이 없으면 비워 두지 말고 없다고 명시해 AI가 인증 설명을 멋대로 만들지 않게 하세요.
- 기본 주소 설명: 테스트 환경과 운영 환경을 구분하는 수준의 환경 설명만 쓰세요. 실제 키나 자격 증명을 프롬프트에 넣지 마세요.
초안을 받으면 먼저 확인할 세 곳
첫째, 필드를 코드와 하나씩 대조하세요. AI는 선택 파라미터를 필수로 적거나 코드에 없는 필드를 예시에 넣기도 하므로, 파라미터 표를 구조체와 글자 단위로 비교해야 합니다. 둘째, 오류 코드가 과하게 채워지지 않았는지 보세요. 코드에서 검색되지 않는 오류 코드와 상태 코드는 오류 설명이 아니라 미확인 목록으로 옮겨야 합니다. 셋째, 예시 데이터를 제대로 마스킹하세요. 전화번호, 이메일, 주문번호는 명백히 가짜인 값으로 바꾸고, 연동 때 쓴 실제 데이터를 문서에 남기지 마세요.
여러 엔드포인트의 문서를 한꺼번에 보완할 때는 한 번에 하나씩 생성해야 필드 표기가 흔들리지 않습니다. 열 개를 한 번에 붙이면 파라미터 표끼리 섞이기 쉽습니다. 순서를 거꾸로 쓰는 방법도 있습니다. 연동 중 파라미터가 맞지 않는다는 말을 들으면 먼저 디버깅 프롬프트: 오류와 코드를 붙이면 근본 원인까지 한 번에 로 문서의 잘못인지 호출의 잘못인지 가른 뒤, 이 페이지를 고치세요.
