처음부터 OpenAPI 사양을 만드는 데 어려움을 겪어본 적이 있나요? 그러면 퍼즐을 조립하는 것과 비슷하다는 것을 알 것입니다. 어떤 사람에게는 재미있고, 어떤 사람에게는 지루할 수 있습니다. 하지만 만약 그렇게 쉽게 만들 수 있는 슈퍼 스마트 AI 조수가 있다면 어떻게 될까요? 바로 Gemini 2.5 Pro입니다. 구글의 최신 똑똑한 모델로, 최소한의 번거로움으로 깨끗하고 정확한 OpenAPI 사양을 작성하도록 도와줍니다. 이 튜토리얼에서는 Gemini 2.5 Pro를 사용하여 전문가처럼 API를 설계하는 방법을 안내할 것입니다. 모든 과정을 간편하고 대화형으로 진행할 수 있습니다. API 설계를 새로운 취미로 삼을 준비가 되셨나요? 그럼 시작해봅시다!
OpenAPI란 무엇이며 왜 Gemini 2.5 Pro를 사용해야 할까요?
우선, OpenAPI가 무엇인지 정리해봅시다. OpenAPI는 RESTful API를 기계가 읽을 수 있는 형식으로 정의하기 위한 표준으로(과거의 Swagger), 엔드포인트, 매개변수, 응답 등을 설명하는 JSON 또는 YAML 파일을 생각하면 됩니다. API 문서, 클라이언트 SDK 및 테스트 도구의 기본 설계도입니다. 손으로 작성하는 것은? 경로, 스키마 및 오류 코드를 입력하는 데 몇 시간이 걸립니다. 지루하죠.
그렇다면 Gemini 2.5 Pro를 사용해야 하는 이유는 무엇일까요? 2025년 3월에 출시된 이 AI 모델은 100만 개 토큰의 컨텍스트 창을 가진 코딩의 괴물입니다(테스트에서는 200만 개!). “사고 모델”이라고 불리며, 인간처럼 작업을 추론할 수 있어 구조화된 OpenAPI 사양 생성을 완벽하게 도와줍니다. 새로운 API를 구상하고 있거나 기존 API를 다듬고 있다면, Gemini 2.5 Pro가 "엔드포인트"라고 말하기도 전에 YAML 또는 JSON을 더 빨리 생성할 수 있습니다. 또한 가장자리에 있는 경우를 잡아내는 특별한 재능이 있습니다—경험이 많은 개발자들도 놓치는 부분입니다. 어떻게 작동하는지 살펴보겠습니다!
OpenAPI 작성을 위한 Gemini 2.5 Pro 시작하기
사용자 정의 스크립트를 수정할 필요가 없습니다—Gemini 2.5 Pro는 Google AI Studio에서 바로 사용할 수 있습니다. 시작하는 방법은 다음과 같습니다:
1단계: Google AI Studio에 가입하기
Google AI Studio에 접속하여 Google 계정으로 등록합니다. 가벼운 사용은 빠르고 무료입니다(유료 플랜을 이용하면 더 높은 한도를 사용할 수 있습니다). 가입 후:
- “API 키 생성”을 클릭하고 안전한 곳에 저장합니다(공개 레포지토리에 저장하지 마세요!).
- 모델 선택기로 이동하여 Gemini 2.5 Pro를 선택합니다(“gemini-2.5-pro-exp-03-25” 또는 유사한 것을 찾으세요).
- 이제 스튜디오의 인터페이스에서 모델과 직접 채팅할 준비가 되었습니다—코딩은 필요 없습니다!
2단계: 프롬프트 인터페이스 열기
Google AI Studio에서는 텍스트 박스가 보이며, 프롬프트를 입력할 수 있습니다. 여기서 Gemini 2.5 Pro에게 우리 OpenAPI 사양을 생성해 달라고 요청할 것입니다. 이 인터페이스는 매우 직관적입니다—그냥 입력하고 “실행”을 누르면 마법처럼 결과가 발생합니다. 또한 출력을 미세 조정하기 위해 온도와 같은 설정을 조정할 수 있습니다(구조화된 출력을 위해 0.7을 유지하세요).
Gemini 2.5 Pro로 첫 번째 OpenAPI 사양 작성하기
간단하지만 강력한 투두 리스트 API를 위한 OpenAPI 사양을 YAML로 작성해봅시다. 처음부터 시작하여 차근차근 만들어보겠습니다.
1단계: 명확한 프롬프트 작성하기
Gemini 2.5 Pro는 구체적인 지시 사항을 잘 이해하므로, 명확하게 전달해 보겠습니다. Google AI Studio의 프롬프트 박스에 입력하세요:
>> 당신은 전문 API 디자이너입니다. 투두 리스트 API를 위한 유효한 OpenAPI 3.0.2 사양을 YAML로 생성하십시오. 포함할 내용은 다음과 같습니다:
- API 정보(제목, 버전, 설명)
- 작업 생성, 읽기, 업데이트 및 삭제를 위한 엔드포인트
- 작업 객체에 대한 스키마(id, 제목, 완료 여부, 생성일)
- 각 엔드포인트에 대한 예제 응답
- 기본 오류 응답(예: 404, 400)
사양이 깔끔하고 OpenAPI 모범 사례를 따르며 사용할 준비가 되도록 하세요.“실행”을 누르면 Gemini 2.5 Pro가 다음과 같은 결과를 제공할 것입니다(명확성을 위해 생략됨):
openapi: 3.0.2
info:
title: 투두 리스트 API
version: 1.0.0
description: 투두 작업을 관리하기 위한 간단한 API
paths:
/tasks:
get:
summary: 모든 작업 목록
responses:
'200':
description: 성공적인 응답
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Task'
post:
summary: 새로운 작업 생성
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TaskInput'
responses:
'201':
description: 작업 생성됨
components:
schemas:
Task:
type: object
properties:
id:
type: integer
title:
type: string
completed:
type: boolean
created_at:
type: string
format: date-time
TaskInput:
type: object
properties:
title:
type: string
completed:
type: boolean
이것은 멋진 초안입니다—Gemini 2.5 Pro가 기본을 완벽히 잡았습니다!
2단계: 저장하기
Google AI Studio에서 생성된 YAML 출력을 복사하여 todo-api.yaml이라는 파일에 붙여넣습니다. 원하신다면 스튜디오 인터페이스에서 직접 다운로드할 수도 있습니다. 이 파일이 출발점이며, 곧 다듬겠습니다.
Rate My OpenAPI로 내 OpenAPI 사양 평가하기
사양을 수정하기 전에 Rate My OpenAPI를 사용하여 몇 점인지 확인해 보겠습니다. 이 유용한 사이트는 당신의 OpenAPI 사양을 100점 만점으로 평가하고 빛나게 만들 수 있는 실행 가능한 조언을 제공합니다.
1단계: 업로드하고 점수 확인하기
- ratemyopenapi.com를 방문하세요.
- todo-api.yaml을 업로드하거나 YAML을 직접 붙여넣습니다.
- “분석” 버튼을 클릭하세요. 사이트가 점수를 계산하여 예를 들어 87/100와 같은 점수와 함께 다음과 같은 팁을 제공할 것입니다:
- “인증을 위한 보안 체계를 추가하세요.”
- “엔드포인트에 대한 설명을 더 자세히 포함하세요.”
- “GET /tasks에 대한 페이지 매김 매개변수를 추가하는 것을 고려하세요.”
2단계: 피드백 해석하기
87점은 좋은 점수이나, A+를 원합니다! 피드백에 따르면 우리의 사양은 인증에 대한 부분이 부족하고 더 풍부한 메타데이터가 필요하다고 합니다. Gemini 2.5 Pro가 최소한으로 유지했을 수도 있습니다—이를 수정해 보겠습니다.
Refining Your OpenAPI Spec with Gemini 2.5 Pro
Rate My OpenAPI의 조언을 바탕으로, 이제 반복해 봅시다. Google AI Studio로 돌아가 Gemini 2.5 Pro에게 점수를 올릴 수 있는 새로운 프롬프트를 제공하겠습니다.
프롬프트 1: 인증 추가하기
프롬프트 박스에 다음을 입력하세요:
>> 내 투두 리스트 OpenAPI 사양을 API 키 인증을 포함하도록 업데이트하세요. 보안 체계를 추가하고 모든 엔드포인트에 적용하세요. 나머지 사양은 그대로 유지하세요. 현재 사양은 다음과 같습니다:
[PASTE YOUR todo-api.yaml CONTENT]
실행하면 Gemini 2.5 Pro가 다음과 같은 내용을 추가할 수 있습니다:
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
security:
- ApiKeyAuth: []이렇게 하면 당신의 API를 보호할 수 있습니다—Rate My OpenAPI가 이 점을 좋아할 것입니다!
프롬프트 2: 설명 보강하기
다음으로, 얇은 설명을 다루어 봅시다:
>> 각 엔드포인트에 대해 최소 2문장 이상의 자세한 설명으로 내 투두 리스트 OpenAPI 사양을 보강하세요. API 정보 섹션에 대한 요약도 추가하세요. 현재 사양은 다음과 같습니다:
[PASTE YOUR UPDATED todo-api.yaml CONTENT]결과는 다음과 같은 내용을 포함할 수 있습니다:
info:
title: 투두 리스트 API
version: 1.0.0
description: 투두 작업을 관리하기 위한 간단한 API입니다. 작업을 쉽게 생성, 읽기, 업데이트 및 삭제할 수 있으며, API 키 인증으로 보호됩니다.
paths:
/tasks:
get:
summary: 모든 작업 리스트
description: 시스템의 모든 작업을 검색하며, 생성 날짜순으로 정렬됩니다. 쿼리 매개변수를 통해 완료 상태로 필터링을 지원합니다.이러한 더 풍부한 세부 정보가 당신의 점수를 90에 가깝게 올려줄 것입니다.
프롬프트 3: 페이지 매김 추가하기
마지막으로 페이지 매김을 다뤄봅시다:
>> 내 투두 리스트 OpenAPI 사양을 GET /tasks 엔드포인트에 페이지 매김 매개변수(제한, 오프셋)를 추가하도록 업데이트하세요. 예제 응답도 포함하세요. 현재 사양은 다음과 같습니다:
[PASTE YOUR LATEST todo-api.yaml CONTENT]Gemini 2.5 Pro는 다음과 같은 내용을 추가할 수 있습니다:
paths:
/tasks:
get:
parameters:
- name: limit
in: query
schema:
type: integer
default: 10
- name: offset
in: query
schema:
type: integer
default: 0
Rate My OpenAPI에 다시 업로드하면—부웅, 아마도 98/100을 받을 수 있습니다! 여전히 부족하다면 다시 수정하세요(예: “제한 헤더 추가”).
엣지 케이스 다루기
더 많은 시나리오를 다루고 싶으신가요? 물어보세요:
>> /tasks/{id} 엔드포인트의 잘못된 작업 ID 및 중복 제목에 대한 오류 응답을 추가하세요.
Gemini 2.5 Pro는 상세한 400 및 409 응답을 추가하여 당신의 사양을 강력하게 유지합니다.
정제된 OpenAPI 사양 테스트하기
당신의 사양은 훌륭해 보입니다—테스트할 시간입니다!
1단계: Apidog으로 모킹하기
todo-api.yaml을 apidog.com에 가져오고 모의 서버를 시작합니다. /tasks에 POST를 시도해보세요:
{
"title": "OpenAPI 배우기",
"completed": false
}
Apidog은 201 응답을 가짜로 생성할 것입니다—실제 백엔드 없이 프로토타이핑하기에 좋습니다.
2단계: 문서 생성하기
Apidog 또는 Swagger UI를 사용하여 사양을 인터랙티브 문서로 렌더링합니다. 팀과 링크를 공유하세요—그들이 얼마나 전문적인지 놀랄 것입니다!
왜 Gemini 2.5 Pro가 OpenAPI 디자인에 적합한가?
그렇다면 다른 도구를 사용하거나 직접 입력하는 것보다 왜 Gemini 2.5 Pro를 선택해야 할까요? 여기 그 이유가 있습니다:
- 속도: 초안 작성이 몇 초 만에 끝납니다, 몇 시간이 아닙니다.
- 정확성: 이렇게 큰 컨텍스트 창 덕분에 복잡한 요구 사항을 잊지 않고 잘 이해합니다.
- 유연성: YAML, JSON, 인증, 오류—모두 처리합니다.
- 학습 곡선: OpenAPI에 처음인 경우에도 Gemini 2.5 Pro가 명확한 출력을 통해 안내합니다.
Claude나 Copilot에 비해 Gemini 2.5 Pro의 추론은 이러한 구조화된 작업에서 빛을 발합니다. 마치 연락 가능한 수석 개발자가 있는 것과 같습니다!
OpenAPI 성공을 위한 프로 팁
- 구체적으로 명시하세요: “API 사양 작성하기”와 같은 모호한 프롬프트는 혼란스러워집니다. 어떤 엔드포인트나 스키마를 원하는지 정확하게 말씀하세요.
- 반복하세요: Gemini 2.5 Pro를 사용하여 개선합니다—작은 조정이 큰 성과로 이어집니다.
- 조기에 검증하세요: 사양을 Apidog 또는 Swagger Editor를 통해 실행하여 이상한 점을 잡으세요.
- 문서 탐색하기: 더 많은 Gemini 2.5 Pro 트릭을 알아보려면 ai.google.dev를 확인하세요.
결론
이제 여러분은 Gemini 2.5 Pro를 사용하여 OpenAPI 사양을 작성하는 전문가가 되었습니다! 투두 API를 설계하고 인증을 추가하고 이를 테스트하는 모든 과정을 통해 이 AI가 API 디자인을 얼마나 재미있고 빠르게 만드는지 보았습니다. 다음 큰 앱을 구축하기 위해서건, 단순히 기술에 열중하기 위해서건, Gemini 2.5 Pro는 당신의 믿음직한 동반자입니다. 다음에는 어떤 API를 설계할 건가요? 애완동물 가게나 날씨 앱 같은 건 어떨까요? 그리고 항상 apidog.com에서 사양을 다듬는 것을 잊지 마세요.