귀찮은 API 문서화, 코드만 주면 Swagger가 뚝딱
📝 귀찮은 API 문서화, 코드만 주면 Swagger가 뚝딱
- 🎯 추천 대상: “문서화는 나중에”라며 미루다가 등짝 맞는 백엔드 개발자
- ⏱️ 소요 시간: 30분 → 1분 단축
- 🤖 추천 모델: 모든 대화형 AI (ChatGPT, Claude, Gemini 등)
“개발 다 했으면 문서도 주셔야죠? (프론트엔드 개발자)” “아… 잠시만요. (아직 한 줄도 안 씀)”
API 개발보다 문서 작성이 더 싫은 거, 저만 그런가요? 파라미터 타입, 필수 여부, 응답 예시 하나하나 적다 보면 현타가 옵니다. 이제 컨트롤러 코드만 긁어서 붙여넣으세요. AI가 깔끔한 Swagger 스펙으로 변환해 드립니다.
⚡️ 3줄 요약 (TL;DR)
- 코드 기반으로 정확한 파라미터/응답 명세 추출
- OpenAPI(Swagger) YAML/JSON 포맷 자동 생성
- 이해하기 쉬운 설명과 예시 데이터 포함
🚀 해결책: “API 문서 생성기”
아래 PROMPT 내용을 복사해서 사용하세요.
역할 (Role): 너는 꼼꼼한 테크니컬 라이터이자 백엔드 개발자야.
상황 (Context): 내가 개발한 API 코드가 있는데, 이를 프론트엔드 개발자와 공유하기 위해 문서화해야 해.
요청 (Task): 아래 제공된 API 코드를 분석하여 [원하는 포맷 선택: OpenAPI 3.0 YAML / Markdown Table] 형식으로 문서를 작성해줘. 반드시 다음 내용을 포함해야 해:
- Endpoint & Method: URL 경로와 HTTP 메서드
- Summary: API가 하는 일에 대한 간략한 요약
- Request Parameters: Body, Query, Path 파라미터 (타입, 필수 여부, 설명 포함)
- Response: 성공(200) 및 실패(400, 500 등) 시의 응답 구조와 예시 JSON
코드:
[여기에 컨트롤러/라우터 코드를 붙여넣으세요]제약사항 (Constraints):
- 데이터 타입(String, Integer 등)을 명확히 명시해줘.
- 응답 예시(Example Value)는 현실적인 데이터로 채워줘.
🧬 프롬프트 해부 (Why it works?)
이 프롬프트가 강력한 이유는 3가지 논리적 장치 때문입니다.
- 포맷 선택: YAML(Swagger용)과 마크다운(위키/노션용) 중 필요한 형식을 고를 수 있게 하여 활용도를 높였습니다.
- 구조화된 요구: 단순히 “문서 써줘”가 아니라 파라미터, 응답, 예시 등 필수 요소를 콕 집어 명시했습니다.
- 현실적 예시:
foo,bar같은 무의미한 값이 아니라 실제 서비스에서 쓸법한 데이터(user123,hong@test.com)를 요구하여 가독성을 높였습니다.
📊 증명: Before & After
❌ Before (입력 코드 - Node.js Express)
app.post("/users", (req, res) => {
const { username, email } = req.body;
if (!email) return res.status(400).send({ msg: "no email" });
// DB 저장 로직...
res.status(201).send({ id: 1, username, email });
});✅ After (결과 - Markdown 예시)
POST /users
사용자 회원가입 API
Request Body
| 필드명 | 타입 | 필수 | 설명 |
|---|---|---|---|
username | String | O | 사용자 닉네임 |
email | String | O | 사용자 이메일 (유니크) |
Response (201 Created)
{
"id": 1,
"username": "jay_dev",
"email": "jay@example.com"
}🚨 트러블 슈팅 (안 될 땐 이렇게!)
Q. DTO 클래스가 별도 파일에 있어요. A. 컨트롤러 코드뿐만 아니라 요청/응답 객체(DTO) 코드도 함께 붙여넣어야 정확한 타입 추론이 가능합니다.
Q. Swagger YAML 문법이 틀렸대요. A. “OpenAPI 3.0.0 스펙을 엄격하게 준수해서 YAML 문법 오류가 없도록 해줘” 라고 제약사항을 추가하세요.
🎯 결론
문서화는 개발의 끝이 아니라 협업의 시작입니다. 하지만 그 시작을 위해 너무 많은 에너지를 쓰진 마세요. AI에게 맡기고 여러분은 비즈니스 로직에 집중하세요! 🍷