Task 01 API 계약서 생성 실습 가이드
📥 실습 입력 (Input)
- •
day4_meeting_notes.md(회의록)
💾 실습 출력 (Output)
- •
erd-schema.md(데이터 명세 및 ERD)
1. 스토리 및 실습 배경
프로젝트에서 화면 설계가 완료되면 프론트엔드와 백엔드 개발자는 어떤 데이터를 주고받을지 먼저 협의해야 합니다. 하지만 구두 회의나 메모장 수준으로 API를 정의하다 보면 꼭 필요한 데이터 필드가 누락되거나, 필드의 영문 이름 및 데이터 타입(String, Number, Boolean)을 서로 다르게 정의하여 실제 화면을 그릴 때 API 통신 오류로 화면이 하얗게 굳어버리는 장애가 발생하곤 합니다.
이번 실습에서는 Codex를 활용하여 비정형화된 기획 요구사항 정의서와 화면 정의서를 기반으로 기획 의도와 100% 매핑되는 표준화된 API 계약서(API Contract)를 자동 생성하고, 프론트엔드와 백엔드가 동일한 규격을 공유하여 마찰 없이 개발을 시작할 수 있도록 돕는 워크플로우를 학습합니다.
2. 학습 목표
- 비정형 요구사항 명세에서 API 형태로 노출할 비즈니스 행위(Endpoint)를 도출할 수 있다.
- 화면 UI 컴포넌트와 API Request/Response 필드 간 매핑 관계를 정의할 수 있다.
- AI를 활용해 RESTful 규칙에 어긋남이 없는 API 명세서 초안을 고속으로 빌드할 수 있다.
- 개발 시작 전에 프론트/백엔드 규격 계약을 맺을 수 있다.
🛠️ 실제 따라 하기 실습 가이드
- 실습용 파일 생성: 아래 다운로드 버튼을 눌러
day4_meeting_notes.md파일을automation/폴더 내에 저장합니다. - Codex 검토 위임: 두 파일을 선택하고 Codex Client 프롬프트 입력창에 아래 **Codex 요청 프롬프트**를 전송하여 빌드합니다.
- API 규격 확인: 출력된 명세서에서 `/api/v1/reservations` 등의 API Endpoint와 필드명, JSON Request/Response 형태가 맞는지 검토합니다.
실습 자료 다운로드
Codex 요청 프롬프트
Task 01 Prompt
제공된 요구사항 정의서와 화면 정의서 내용을 기반으로, 필요한 API 목록을 도출하고 요청(Request) 및 응답(Response) 필드의 타입과 영문 변수명을 정의하여 표준 API 계약서(API Contract)를 작성해 주세요.
4. 결과물 예시
Codex는 명세 데이터를 종합 분석하여 아래와 같이 정규화된 API 계약서를 작성합니다.
| 엔티티명 | 설명 | 주요 속성 | 관계 정보 |
|---|---|---|---|
| POST /api/v1/reservations | 상담 서비스를 이용하는 일반 회원 | Request: expert_id, reservation_date | Reservation과 1:N 관계 |
| Response: 201 Created | 상담을 제공하는 파트너 전문가 | expert_id (PK), name, category | Reservation과 1:N 관계 |
| GET /api/v1/experts | 사용자-전문가 간 예약 매핑 정보 | Request: category (query parameter) | User/Expert와 N:1, Payment와 1:1 관계 |
| Response: 200 OK | 예약 확정을 위한 결제 거래 정보 | Response: list of expert objects | Reservation과 1:1 관계 |
5. AI 활용 포인트
- 화면-데이터 매핑: 화면 기획에 표시되어야 하는 정보(전문가 정보, 날짜 등)를 기준으로 백엔드 응답 필드를 누락 없이 자동 식별.
- RESTful 네이밍: 비즈니스 행위를 명사형 엔드포인트 규칙과 HTTP Method로 자동 변환 및 타입 정의.