서론
개발팀에 AI 코딩 어시스턴트가 도입된 지 1년이 넘었지만, 여전히 프론트엔드 개발자들은 API 엔드포인트를 하나씩 복사해서 프롬프트에 붙여넣고 있습니다. “이 엔드포인트로 폼 만들어줘”, “이 응답 구조로 테이블 만들어줘"를 수십 번 반복하면서 말이죠. 심지어 중간에 필드가 추가되거나 타입이 변경되면 다시 프롬프트를 수정해서 AI에게 물어봐야 합니다.
이것은 근본적으로 비효율적입니다. 백엔드 팀이 이미 Swagger(OpenAPI) 스펙을 작성해두었다면, AI가 프론트엔드를 생성하는 데 필요한 모든 컨텍스트가 이미 기계가 읽을 수 있는 형태로 존재하기 때문입니다. 엔드포인트 경로, HTTP 메서드, 요청/응답 스키마, 필드 타입, 필수 여부, 제약조건, 심지어 예시 값까지요.
대부분의 팀은 이 사실을 간과합니다. Swagger UI를 문서화 도구로만 생각하지, AI 코드 생성의 구조적 컨텍스트로 활용할 수 있다는 점을 놓치고 있습니다. 이 글에서는 OpenAPI 스펙을 컨텍스트로 활용하여 AI가 프론트엔드 코드를 자동으로 생성하게 만드는 구체적인 방법론을 다룹니다.
왜 OpenAPI가 완벽한 컨텍스트인가
구조화된 정보의 밀도
OpenAPI 스펙은 일반적인 자연어 문서와 근본적으로 다릅니다. 모호함이 없습니다. GET /users/{id} 엔드포인트가 있다면, 응답 스키마에 id는 integer, email은 string이고 format: email이라는 제약조건까지 명시되어 있습니다. AI에게 이 정보를 제공하면, 프론트엔드 개발자가 매번 설명하던 “이 필드는 이메일 형식이에요”, “이건 필수 항목이에요” 같은 맥락을 전달할 필요가 없어집니다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
| {
"paths": {
"/users": {
"get": {
"summary": "사용자 목록 조회",
"parameters": [
{
"name": "page",
"in": "query",
"schema": { "type": "integer", "default": 1 }
},
{
"name": "limit",
"in": "query",
"schema": { "type": "integer", "default": 20 }
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "array",
"items": { "$ref": "#/components/schemas/User" }
}
}
}
}
}
}
}
}
}
|
이 JSON 구조 하나가 AI에게 전달하는 정보량은 상당합니다. 페이지네이션이 필요하다는 것, 응답이 배열 형태라는 것, 각 아이템이 User 스키마를 따른다는 것까지 한 번에 파악할 수 있습니다.
수동 프롬프트 엔지니어링과의 비교
| 비교 항목 | 수동 프롬프트 입력 | OpenAPI 스펙 활용 | | :— | :— | :— | | 컨텍스트 전달 방식 | 개발자가 매번 텍스트로 설명 | 기계가 읽을 수 있는 구조화된 스펙 | | 정보 누락 위험 | 높음 (필드 놓침, 타입 오기) | 낮음 (스펙에 이미 정의됨) | | API 변경 대응 | 프롬프트 전체 재작성 | 스펙 파일만 교체 | | 일관성 | 프롬프트마다 상이 | 동일 스펙 기반으로 항상 동일 | | 생성 가능한 범위 | 단일 컴포넌트 한계 | 전체 CRUD 페이지 생성 가능 |
이 차이는 단순한 편의성의 문제가 아닙니다. 생성된 코드의 정확도와 일관성에 직접적으로 영향을 미칩니다.
전체 파이프라인 구조
OpenAPI 스펙을 활용한 AI 프론트엔드 자동 생성의 전체 흐름은 다음과 같습니다.
1
2
3
4
5
6
7
| graph LR
A[OpenAPI JSON/YAML] --> B[스펙 파서]
B --> C[컨텍스트 템플릿]
C --> D[LLM API 호출]
D --> E[React/Vue 컴포넌트]
E --> F[코드 검증]
F --> G[프로젝트 통합]
|
각 단계를 구체적으로 살펴보겠습니다.
Step-by-Step 구현 가이드
Step 1: OpenAPI 스펙 파싱하기
먼저 Swagger 엔드포인트에서 스펙을 가져와서 AI가 처리하기 좋은 형태로 변환해야 합니다. Python과 openapi-core 라이브러리를 사용하면 쉽게 파싱할 수 있습니다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
| import json
import requests
from typing import Dict, List, Any
class OpenAPIParser:
"""OpenAPI 스펙을 파싱하여 AI 컨텍스트로 변환하는 클래스"""
def __init__(self, spec_url: str):
self.spec_url = spec_url
self.spec = self._fetch_spec()
def _fetch_spec(self) -> dict:
"""Swagger 엔드포인트에서 스펙을 가져옵니다"""
response = requests.get(self.spec_url)
response.raise_for_status()
return response.json()
def extract_endpoints(self) -> List[Dict[str, Any]]:
"""모든 엔드포인트 정보를 추출합니다"""
endpoints = []
for path, methods in self.spec.get("paths", {}).items():
for method, details in methods.items():
if method in ("get", "post", "put", "patch", "delete"):
endpoint = {
"path": path,
"method": method.upper(),
"summary": details.get("summary", ""),
"parameters": details.get("parameters", []),
"request_body": self._extract_request_body(details),
"response_schema": self._extract_response_schema(details),
"tags": details.get("tags", [])
}
endpoints.append(endpoint)
return endpoints
def _extract_request_body(self, details: dict) -> dict:
"""요청 본문 스키마를 추출합니다"""
request_body = details.get("requestBody", {})
content = request_body.get("content", {})
for content_type, schema_info in content.items():
if "schema" in schema_info:
return self._resolve_refs(schema_info["schema"])
return {}
def _extract_response_schema(self, details: dict) -> dict:
"""200 응답의 스키마를 추출합니다"""
responses = details.get("responses", {})
success_response = responses.get("200", responses.get("201", {}))
content = success_response.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
| get("content", {})
for content_type, schema_info in content.items():
if "schema" in schema_info:
return self._resolve_refs(schema_info["schema"])
return {}
def _resolve_refs(self, schema: dict) -> dict:
"""$ref 참조를 실제 스키마로 해결합니다"""
if "$ref" in schema:
ref_path = schema["$ref"].replace("#/", "").split("/")
resolved = self.spec
for part in ref_path:
resolved = resolved.get(part, {})
return resolved
if "properties" in schema:
for key, value in schema["properties"].items():
if "$ref" in value:
schema["properties"][key] = self._resolve_refs(value)
return schema
def generate_context_for_endpoint(self, endpoint: dict) -> str:
"""단일 엔드포인트에 대한 AI 컨텍스트를 생성합니다"""
context = f"""
엔드포인트: {endpoint['method']} {endpoint['path']}
설명: {endpoint['summary']}
태그: {', '.join(endpoint['tags'])}
요청 파라미터:
{json.dumps(endpoint['parameters'], indent=2, ensure_ascii=False)}
요청 본문 스키마:
{json.dumps(endpoint['request_body'], indent=2, ensure_ascii=False)}
응답 스키마:
{json.dumps(endpoint['response_schema'], indent=2, ensure_ascii=False)}
"""
return context.strip()
# 사용 예시
parser = OpenAPIParser("http://localhost:8000/openapi.json")
endpoints = parser.extract_endpoints()
for ep in endpoints:
if "users" in ep["path"]:
print(parser.generate_context_for_endpoint(ep))
print("---")
|
이 코드는 Swagger 엔드포인트에서 스펙을 가져와서 $ref 참조를 해결하고, 각 엔드포인트에 대해 AI가 이해하기 쉬운 컨텍스트 텍스트를 생성합니다.
Step 2: AI 프롬프트 템플릿 구성하기
파싱된 정보를 LLM에 전달할 때, 단순히 스펙을 던져주는 것보다 구조화된 프롬프트 템플릿을 사용하는 것이 좋습니다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
| SYSTEM_PROMPT = """당신은 React + TypeScript 프론트엔드 개발자입니다.
OpenAPI 스펙을 기반으로 다음 규칙을 따라 코드를 생성하세요:
1. 모든 API 호출은 커스텀 훅(useQuery, useMutation)으로 분리
2. 폼은 react-hook-form + zod로 유효성 검사
3. 테이블은 페이지네이션을 포함
4. 에러 처리는 toast 알림으로 통일
5. 스키마에 정의된 타입을 그대로 TypeScript 타입으로 사용
6. 필수 필드(required)는 폼에서 mark 표시
7. enum 값은 Select 컴포넌트의 옵션으로 자동 매핑
프레임워크: React 18 + TypeScript + TanStack Query + shadcn/ui
"""
USER_PROMPT_TEMPLATE = """
다음 OpenAPI 엔드포인트에 대한 프론트엔드 코드를 생성하세요.
## API 스펙
{api_context}
## 요청사항
- 목록 조회 페이지 (테이블 + 검색 + 페이지네이션)
- 상세 조회 페이지
- 생성/수정 폼 (모달)
- 삭제 확인 다이얼로그
다음 파일을 생성하세요:
1. types.ts - API 타입 정의
2. api.ts - API 호출 함수 (TanStack Query hooks)
3. columns.tsx - 테이블 컬럼 정의
4. UserTable.tsx - 메인 테이블 컴포넌트
5. UserForm.tsx - 생성/수정 폼 컴포넌트
"""
|
이 템플릿의 핵심은 스펙에서 추론 가능한 모든 것을 AI가 자동으로 처리하도록 지시한다는 점입니다. 개발자가 “이 필드는 이메일이에요"라고 설명할 필요가 없습니다. 스펙에 format: email이 있으면 AI가 자동으로 zod 스키마에 .email() 검증을 추가합니다.
Step 3: 생성 파이프라인 실행하기
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
| import anthropic
class FrontendGenerator:
"""OpenAPI 스펙 기반 프론트엔드 코드 생성기"""
def __init__(self, api_key: str):
self.client = anthropic.Anthropic(api_key=api_key)
self.parser = None
def generate_for_resource(
self,
spec_url: str,
resource_tag: str
) -> Dict[str, str]:
"""특정 리소스에 대한 전체 프론트엔드 코드를 생성합니다"""
# 1. 스펙 파싱
self.parser = OpenAPIParser(spec_url)
endpoints = self.parser.extract_endpoints()
# 2. 관련 엔드포인트 필터링
resource_endpoints = [
ep for ep in endpoints
if resource_tag in ep["tags"] or resource_tag in ep["path"]
]
# 3. 컨텍스트 결합
combined_context = "
".join([
self.parser.generate_context_for_endpoint(ep)
for ep in resource_endpoints
])
# 4. AI 호출
user_prompt = USER_PROMPT_TEMPLATE.format(
api_context=combined_context
)
response = self.client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=8000,
system=SYSTEM_PROMPT,
messages=[
{"role": "user", "content": user_prompt}
]
)
# 5. 응답에서 파일별 코드 추출
generated_code = response.content[0].text
return self._parse_generated_files(generated_code)
def _parse_generated_files(self, code: str) -> Dict[str, str]:
"""AI 응답에서 파일별 코드를 분리합니다"""
files = {}
current_file = None
current_content = []
for line in code.split("
"):
# 파일명 패턴 감지
if line.strip().startswith("// 파일:") or \
line.strip().startswith("```") and \
any(ext in line for ext in [".ts", ".tsx"]):
if current_file and current_content:
files[current_file] = "
".
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
| join(current_content)
# 새 파일 시작
current_file = line.split(":")[-1].strip() if ":" in line else "unknown"
current_content = []
else:
current_content.append(line)
if current_file and current_content:
files[current_file] = "
".join(current_content)
return files
# 실행 예시
generator = FrontendGenerator(api_key="your-api-key")
files = generator.generate_for_resource(
spec_url="http://localhost:8000/openapi.json",
resource_tag="users"
)
for filename, code in files.items():
print(f"
{'='*60}")
print(f"파일: {filename}")
print(f"{'='*60}")
print(code[:500] + "..." if len(code) > 500 else code)
|
Step 4: 생성된 코드 검증하기
AI가 생성한 코드라고 해서 무조건 신뢰할 수는 없습니다. 스펙과의 일치성을 검증하는 단계가 필요합니다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| import subprocess
import os
class CodeValidator:
"""생성된 코드의 스펙 준수 여부를 검증합니다"""
def __init__(self, output_dir: str, spec: dict):
self.output_dir = output_dir
self.spec = spec
def validate_types(self) -> List[str]:
"""TypeScript 타입이 스펙과 일치하는지 검사합니다"""
errors = []
# api.ts 파일에서 타입 정의 추출
types_file = os.path.join(self
|
출처: https://news.hada.io/topic?id=28597