우리는 AI로 프롬프트를 적을 떄 “API 스펙 좀 짜줘!” → 이렇게 하면 망합니다 🤦♂️
개발하다 보면 API 스펙을 짜야 할 때가 많습니다.
특히 상품 등록 API 같은 CRUD API는 필수죠!
그런데 요즘 AI에게 API 설계를 맡기는 경우가 많아졌습니다.
✅ AI가 자동으로 스키마를 생성해주고,
✅ 빠르게 API 명세를 정리해주니까요.
하지만 그냥 “상품 등록 API 만들어줘!” 라고 하면?
❌ 제각각 다른 스타일의 응답
❌ 필수 필드 누락
❌ 인증/에러 응답 미비
잘못된 프롬프트는 부실한 API 명세로 이어집니다!
그래서 오늘은!
📌 AI에게 API 설계를 맡길 때 정확한 프롬프트 작성법을 알아보겠습니다.
📌 예제 템플릿도 드릴 테니 바로 활용 가능!
그럼 바로 시작해볼까요? 🚀
1. AI에게 API 설계를 맡길 때, 왜 프롬프트가 중요한가? 🤔
AI는 명확한 지시가 없으면,
알아서 적당히 만든 API 명세를 줄 뿐입니다.
예를 들어,
❌ “상품 등록 API 만들어줘” → 필드 일부 누락, 인증 정보 없음
✅ “상품 등록 API를 Markdown 형식으로 상세히 작성해줘” → 가독성 있는 문서 출력
API 문서는 협업의 핵심입니다.
프롬프트가 부실하면, 팀원들이 API를 이해하는 데 어려움을 겪게 되죠.
따라서, AI가 완전한 API 명세를 생성할 수 있도록 명확하고 구조화된 프롬프트 작성이 필요합니다!
2. AI에게 정확한 API 명세를 요청하는 방법
🚨 “상품 등록 API 만들어줘” → 이렇게 하면 부족한 이유
- 필드 정의 없음 → 어떤 데이터가 필요한지 AI가 모름
- 요청/응답 형식 누락 → JSON 예제가 없을 가능성 큼
- 인증 관련 정보 부족 → API 보안 설정이 빠질 수 있음
- 에러 응답 정의 안됨 → 클라이언트가 예외 상황을 대비하기 어려움
✅ 정확한 프롬프트 작성법
📌 “8개 필드를 갖는 상품 등록 API 명세를 Markdown 형식으로 작성해줘”
📌 “요청/응답 JSON 예제 포함, 인증(JWT) 방식 설명 추가”
이렇게 요청하면 AI가 더 완성도 높은 API 문서를 생성할 수 있습니다!
3. [템플릿] AI에게 API 명세 요청하는 프롬프트 📝
아래 프롬프트를 사용하면, AI가 명확한 API 명세를 생성할 수 있습니다.
## 프롬프트 템플릿: "8개 필드를 갖는 상품 등록 API 명세" 생성
### 지시사항(Instruction)
- 당신(모델)은 **Markdown** 형식으로 **상세한 API 사양(API Specification) 문서**를 작성해주는 **AI 어시스턴트**입니다.
### 요청(Task)
다음 요구사항을 만족하는 **“상품 등록(Create Product)” API 예시**를 만들어 주세요.
- **인풋 필드** 총 8개:
1. productName
2. description
3. price
4. currency
5. stockCount
6. discountRate
7. categoryId
8. tags
- **출력(응답) 포맷**: 반드시 **Markdown** 형태여야 하며, 아래 항목을 **모두** 포함해야 합니다:
1. **엔드포인트 & 개요**: HTTP 메서드, URL 경로, 용도(기능)
2. **요청 헤더**: 필수 헤더(예: Content-Type, Authorization)
3. **요청 바디**: 샘플 JSON, 각 필드의 자료형/제약조건/설명
4. **성공 응답**: 예시 JSON(예: 201 Created), 반환 필드 설명
5. **에러 응답**: 최소 2~3개 (예: 400, 401, 403 등), 예시 JSON 포함
6. **사용 시나리오**: 일반적인 호출 흐름 예시(로그인 → 등록 → 응답 처리 등)
7. **버전 관리**: 예: /api/v1/…
8. **추가 설명**: 필드 검증 규칙, 보안(JWT), 로깅 등
### 예시(Example)
아래와 같은 구성을 가진 Markdown 문서를 반환해주세요:
1. **개요(Overview)**
2. **요청 형식(Request Format)**
- 헤더(Headers)
- 바디(Body)
- 필드 설명(Fields)
3. **응답 형식(Response Format)**
- 성공 응답
- 에러 응답
4. **사용 시나리오(Usage Scenarios)**
5. **버전 관리(Versioning)**
6. **추가 설명(Additional Notes)**
### 주의사항(Constraints)
- 언어는 **한글**을 사용해주세요.
- **유효한 JSON** 예시를 제시해주세요.
- 8개 필드 외에 불필요한 필드를 추가하지 말아주세요.
- 에러 응답의 예시는 **최소 2~3가지**를 보여주세요.
- 요청 헤더나 응답 구조에서 **인증/인가**(예: JWT)를 사용하는 방식을 구체적으로 언급해주시면 좋습니다.
### 스타일(Style)
- **실제 제품 문서**처럼 구체적이고 일관성 있게 작성해주세요.
- 테이블이나 리스트를 활용해 **가독성**을 높여주세요.
- 예시 JSON은 **문법적으로 유효**해야 하며, 실제로 파싱 가능한 형태여야 합니다.
---
이렇게 요청하면AI가 상세한 API 명세를 Markdown 형식으로 생성해줍니다!
4. API 문서에서 “버전 관리”까지 포함하면 좋은 이유
API 버전 관리를 명확히 해야
✅새로운 기능 추가 시, 기존 API가 깨지지 않습니다.
✅클라이언트가 예상치 못한 문제 없이 API를 활용할 수 있습니다.
따라서, AI에게 API 명세를 요청할 때,
버전 정보(/api/v1/vs/api/v2/등)까지 포함하도록 요청하는 것이 좋습니다.
5. AI에게 API 설계를 맡길 때, 꼭 기억해야 할 3가지!
1️⃣명확한 구조 제시→ 엔드포인트, 헤더, 요청 바디, 응답 정의 포함
2️⃣에러 응답 & 보안 포함→ JWT 인증, HTTP 상태 코드 정의 필수
3️⃣버전 관리 명시→/api/v1/형태로 요청하면 API 업데이트 시 혼란 없음
AI가더 정교한 API 문서를 생성할 수 있도록
📌구체적인 프롬프트를 작성해보세요! 🚀
🎯 AI에게 API 설계를 맡길 때 자주 묻는 질문
❓ AI가 만든 API 문서를 그대로 써도 될까요?
👉 기본 구조는 활용 가능하지만,
👉보안 검토 & 필드 검증을 반드시 해야 합니다!
❓ API 명세에서 필드 누락이 발생하면?
👉 “모든 필드를 포함해서 작성해줘” 라고 다시 요청하세요.
👉 AI가 실수할 수도 있으니꼼꼼한 검토 필수!
❓ JWT 인증을 추가하려면?
👉 “Authorization 헤더에 JWT 인증 방식 추가해줘” 라고 명시하면 됩니다!
함께 보면 좋은 글
AI와 함께 일하는 마인드셋 변화 나만의 영화의 감독이 되자!