Blog

기존 요청에서 OpenAPI 스펙 생성 방법

INEZA Felin-Michel

INEZA Felin-Michel

5 December 2025

기존 요청에서 OpenAPI 스펙 생성 방법

맨 처음부터 OpenAPI 명세를 작성하는 것은 특히 API가 이미 작동 중일 때 많은 시간이 소요될 수 있습니다. 많은 팀이 문서화가 거의 없거나 전혀 없는 프로젝트를 물려받거나, 초기 개발 단계에서 빠르게 구축된 API를 다루게 됩니다. 이러한 경우, 문서를 작성하는 가장 실용적인 방법은 기존 API 요청에서 직접 OpenAPI 명세를 생성하는 것입니다.

이 가이드는 이 접근 방식이 왜 효과적인지, 어떤 도구들이 도움이 되는지, 그리고 실제 요청을 팀이 신뢰할 수 있는 깔끔하고 재사용 가능한 OpenAPI 명세로 바꾸는 방법을 설명합니다.

💡
이미 cURL 명령어, HAR 파일, Postman 컬렉션 또는 원시 API 로그가 있다면, OpenAPI 명세를 처음부터 작성할 필요가 없습니다. Apidog는 이 모든 형식을 가져와 즉시 깔끔하고 구조화된 OpenAPI 명세로 변환할 수 있습니다. 각 요청을 분석하고, 모델을 자동으로 생성하며, 한곳에서 모든 것을 다듬을 수 있게 하여 수동 작업 시간을 절약하고 문서의 정확성과 일관성을 유지합니다.

버튼

방법 1: "코드 우선" 접근 방식

이 방법은 백엔드 애플리케이션 코드에 직접 주석이나 라이브러리를 추가할 수 있는 경우에 작동합니다.

작동 방식

웹 프레임워크에 라이브러리를 설치하여 코드(경로, 컨트롤러, 모델)를 검사하고 즉석에서 OpenAPI 명세를 생성합니다.

인기 라이브러리:

FastAPI (Python) 예시:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/", response_model=Item)
async def create_item(item: Item):
    """
    데이터베이스에 새 항목을 생성합니다.
    - **name**: 항목의 이름
    - **price**: 항목의 USD 가격
    """
    return item

# 이 코드는 /docs 또는 /openapi.json에서 전체 OpenAPI 명세를 자동으로 생성합니다.

장점:

단점:

방법 2: "트래픽 분석" 접근 방식

이는 영리한 "외부-내부" 접근 방식입니다. 클라이언트와 API 간의 실제 HTTP 트래픽을 캡처한 다음, 이를 분석하여 명세를 추론합니다.

작동 방식

프록시 또는 네트워크 스니퍼 역할을 하는 도구를 사용합니다. 모든 API 트래픽이 이 도구를 통해 라우팅됩니다. 이 도구는 요청 및 응답(URL, 메서드, 헤더, 본문)을 분석하여 API 모델을 구축합니다.

인기 도구:

프로세스:

  1. 앱 또는 클라이언트를 프록시 도구를 통해 트래픽을 라우팅하도록 구성합니다.
  2. 주요 API 워크플로우(로그인, 데이터 생성, 데이터 가져오기 등)를 실행합니다.
  3. 도구가 패턴을 관찰하고 예비 OpenAPI 명세를 생성합니다.

장점:

단점:

방법 3: "요청 컬렉션" 접근 방식

Apidog 홍보 자료

이는 개발자와 팀에게 가장 실용적이고 효율적인 방법인 경우가 많습니다. 요청을 보내는 것뿐만 아니라 API 디자인도 이해하는 고급 API 클라이언트를 사용합니다. 요청 컬렉션을 구축하면 도구가 요청을 깔끔한 OpenAPI 명세로 구조화하고 내보내는 데 도움을 줍니다.

이것이 바로 Apidog의 강점이 빛을 발하는 곳입니다. 이 워크플로우를 위해 구축되었습니다.

버튼

Apidog에서의 작동 방식

1. 평소대로 요청 보내기: 워크플로우를 변경하지 마세요. Apidog를 사용하여 기존 API 엔드포인트를 테스트하고 디버그하세요. GET, POST, PUT, DELETE 요청을 보내면 Apidog가 모든 세부 정보를 캡처합니다.

2. Apidog가 모델을 구축하도록 하기: 작업하는 동안 Apidog는 백그라운드에서 API의 구조를 이해하기 시작합니다. 엔드포인트, 매개변수, 요청 본문 및 응답 스키마를 파악합니다.

3. 문서로 정리하기: Apidog는 요청을 실시간으로 API 문서로 변환할 수 있습니다. 임시 요청이 도구 내에서 구조화되고 탐색 가능한 API 문서 페이지가 됩니다. 설명을 추가하고, 엔드포인트를 폴더로 그룹화하며, 자동으로 추론된 세부 정보를 정리할 수 있습니다.

4. 명세 내보내기: 컬렉션이 정확하고 잘 설명되면 내보냅니다. 그러면 사용자는 단 한 번의 클릭으로 표준 YAML 또는 JSON 형식으로 OpenAPI 명세를 내보낼 수 있습니다. 이 명세는 Swagger UI와 함께 사용하거나, 다른 도구로 가져오거나, 저장소에 커밋할 준비가 됩니다.

장점:

단점:

방법 4: 수동 작성 접근 방식

때로는 Swagger Editor 또는 Stoplight Studio와 같은 편집기에서 명세를 수동으로 구축해야 할 때도 있습니다. 이는 종종 위에서 설명한 방법들과 함께 진행됩니다.

  1. 요청 컬렉션을 참조로 사용: Postman 컬렉션, cURL 명령어 또는 Apidog 프로젝트를 보조 화면에 열어 둡니다.
  2. 명세를 단계별로 구축: 참조에 있는 각 엔드포인트를 OpenAPI YAML/JSON으로 수동으로 변환합니다. 이렇게 하면 각 매개변수와 응답에 대해 깊이 생각하게 됩니다.
  3. 예시로 유효성 검사: 편집기의 미리보기를 사용하여 명세가 실제 API 동작과 일치하는지 확인합니다.

장점:

단점:

요청에서 OpenAPI 명세를 생성하기 위한 모범 사례

어떤 방법을 사용하든 다음 원칙을 따르세요:

  1. 작게 시작: 하나의 핵심 엔드포인트(예: GET /users)를 선택하세요. 이를 완전히 생성하거나 문서화한 다음 확장하세요.
  2. 빠르고 자주 유효성 검사: OpenAPI 명세를 사용하여 즉시 모의 서버를 생성하세요. 실제 API처럼 작동하나요? 이렇게 하면 불일치를 빠르게 파악할 수 있습니다.
  3. 반복 및 개선: 처음 생성된 명세는 거칠 것입니다. 초안으로 간주하세요. 설명, 예시를 추가하고 스키마 정의를 강화하세요.
  4. 오류 응답 포함: 이것은 종종 놓치는 부분입니다. 명세에 4xx 및 5xx 오류 응답 형식이 문서화되어 있는지 확인하세요.
  5. 인증을 잊지 마세요: securitySchemes 섹션에 API가 어떻게 보호되는지(API 키, OAuth2 등) 문서화하세요.

결론: 당신의 청사진이 기다립니다

기존 요청에서 OpenAPI 명세를 생성하는 것은 가능할 뿐만 아니라, 성숙한 API 프로젝트에 질서를 부여하기 위한 실질적인 필요성입니다. 코드 우선 라이브러리, 트래픽 스니핑 도구 또는 Apidog와 같은 강력한 API 클라이언트를 선택하든, 명확성, 자동화 및 협업에 투자하는 것입니다.

선택하는 방법은 코드베이스 제어, 시간 제약 및 팀 워크플로우와 같은 상황에 따라 달라집니다. 그러나 목표는 동일합니다. 요청 로그, cURL 명령어 및 구두 지식에 담긴 암묵적인 지식을 API를 발전시킬 수 있는 명확하고 기계가 읽을 수 있는 계약으로 변환하는 것입니다.

API의 복잡성이 숨겨져 있도록 두지 마세요. 이미 가지고 있는 요청으로 시작하고, 올바른 도구를 사용하여 필수적인 OpenAPI 청사진을 만드세요. 미래의 당신과 API를 사용해야 할 모든 사람이 감사할 것입니다.

버튼

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드