Rihpig

Posted on Jun 3 • Originally published at apidog.com

아피독 스펙 우선 모드란?

Apidog 스펙 우선 모드(Spec-First Mode)는 OpenAPI 스펙을 소스 코드처럼 관리하려는 팀을 위한 베타 작업 공간입니다. YAML 또는 JSON으로 openapi.yaml / openapi.json을 직접 편집하고, 연결된 Git 저장소와 양방향으로 동기화합니다. 폼 기반 편집기 대신 스펙 파일 자체를 프로젝트의 단일 진실 공급원으로 사용합니다.

오늘 Apidog를 사용해 보세요

이 글에서는 스펙 우선 모드의 사용 흐름, Git 연결 방식, 일상적인 편집-커밋-푸시 루프, 베타에서 주의할 점을 구현 관점에서 정리합니다. Git 기반 API 협업 방식에 대한 더 넓은 배경은 Git-네이티브 API 워크플로우를 참고하십시오.

Apidog 스펙 우선 모드(Spec-First Mode)란?

스펙 우선 모드(Spec-First Mode)는 Apidog에서 OpenAPI 문서를 원시 파일로 편집하는 베타 모드입니다.

핵심 작업은 다음과 같습니다.

Git 저장소를 연결합니다.
저장소의 OpenAPI 스펙 파일을 엽니다.
YAML 또는 JSON을 직접 수정합니다.
스키마 유효성 검사와 자동 완성을 사용합니다.
변경 사항을 커밋합니다.
연결된 브랜치에 푸시합니다.
팀원이 변경한 내용은 다시 pull 하여 동기화합니다.

이 모드는 특히 다음 팀에 적합합니다.

OpenAPI 스펙을 Git에서 버전 관리하는 백엔드 팀
API 계약을 pull request로 리뷰하는 플랫폼 팀
서비스 코드와 API 스펙을 같은 워크플로우에서 관리하려는 엔지니어링 조직
YAML/JSON 직접 편집에 익숙한 API-first 팀

대부분의 API 도구는 그래픽 UI 뒤에 스펙을 숨깁니다. 스펙 우선 모드는 반대로 파일을 직접 보여주고, Git을 중심으로 협업합니다.

스펙 우선 모드와 디자인 우선 모드 비교

Apidog에는 두 가지 API 설계 모드가 있습니다.

디자인 우선 모드(Design-First Mode): 시각적 폼 기반 편집기
스펙 우선 모드(Spec-First Mode): YAML/JSON 코드 편집기

자세한 비교는 스펙 우선 대 디자인 우선 비교를 참고하십시오.

측면	디자인 우선 모드	스펙 우선 모드 베타
주요 편집기	시각적 폼 및 UI 패널	원시 YAML/JSON 코드 편집기
진실 공급원	Apidog 프로젝트 데이터베이스	Git 저장소의 스펙 파일
Git 동기화	내보내기/가져오기 기반	네이티브 양방향 동기화
적합 대상	시각 디자이너, 혼합 팀	Git 네이티브 엔지니어링 팀
학습 곡선	안내형 UI 중심	OpenAPI를 알면 익숙함

둘 중 하나가 항상 더 좋은 것은 아닙니다. 팀이 실제로 API를 작성하고 리뷰하는 방식에 맞춰 선택하는 것이 중요합니다.

주요 기능

1. IDE 스타일 OpenAPI 편집기

스펙 우선 모드의 중심은 OpenAPI 문서를 직접 편집하는 코드 편집기입니다. openapi.yaml 또는 openapi.json 파일을 열고 원시 스펙을 수정합니다.

편집기는 다음 기능을 제공합니다.

YAML/JSON 구문 강조
OpenAPI 및 Swagger 기반 자동 완성
입력 중 스키마 유효성 검사
잘못된 응답 객체, 누락된 필드, 잘못된 $ref 확인
대형 스펙 파일 탐색 지원

예를 들어 다음과 같은 경로 정의를 직접 작성할 수 있습니다.

paths:
  /users/{userId}:
    get:
      summary: Get a user by ID
      operationId: getUserById
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

자동 완성은 additionalProperties, schema, responses, $ref처럼 OpenAPI 구조를 정확히 기억해야 할 때 유용합니다. 편집기가 스펙 구조를 알고 있으므로 잘못된 키나 누락된 필드를 빠르게 발견할 수 있습니다.

2. 자동 파싱되는 탐색 개요

실제 OpenAPI 파일은 수천 줄까지 길어질 수 있습니다. 스펙 우선 모드는 왼쪽 사이드바에서 파일을 자동으로 파싱해 탐색 가능한 개요를 만듭니다.

개요에는 일반적으로 다음 항목이 표시됩니다.

paths
operations
schemas
components

예를 들어 POST /orders 작업을 찾기 위해 줄 번호를 기억할 필요가 없습니다. 개요에서 해당 operation을 클릭하면 편집기가 해당 위치로 이동합니다.

이 기능은 큰 openapi.yaml 파일을 다룰 때 특히 유용합니다. 스크롤이 아니라 API 구조를 기준으로 이동할 수 있습니다.

3. 양방향 Git 동기화

스펙 우선 모드의 핵심은 Git 저장소와의 양방향 동기화입니다.

지원 방식은 다음과 같습니다.

제공업체	연결 방식
GitHub	직접 통합
GitLab	직접 통합
Azure DevOps	일반 Git 연결

연결 후에는 다음 루프를 사용합니다.

pull -> edit -> validate -> commit -> push

pull: 저장소의 최신 변경 사항을 Apidog 편집기로 가져옵니다.
edit: OpenAPI YAML/JSON을 수정합니다.
commit: 변경 사항에 커밋 메시지를 작성합니다.
push: 연결된 저장소와 브랜치에 반영합니다.

GitHub 중심의 상세 흐름은 OpenAPI 스펙을 GitHub에 동기화하는 가이드를 참고하십시오.

4. 커밋, 푸시, 동기화 상태 확인

스펙 우선 모드는 단순 저장 방식이 아니라 Git 커밋 모델을 따릅니다.

일반적인 작업 순서는 다음과 같습니다.

스펙 파일을 수정합니다.
변경된 파일 목록을 확인합니다.
커밋 메시지를 작성합니다.
변경 사항을 커밋합니다.
연결된 브랜치에 푸시합니다.
동기화 상태 표시기를 확인합니다.

동기화 상태 표시기는 로컬 스펙과 원격 저장소의 상태를 알려줍니다. 예를 들어 저장소와 일치하면 “방금 동기화됨”과 같은 상태가 표시됩니다.

이렇게 하면 현재 편집 중인 스펙이 팀원이 보는 버전과 같은지 확인할 수 있습니다.

5. 파일 변경 추적

커밋 전에 변경 사항을 확인할 수 있습니다.

스펙 우선 모드는 파일 단위로 변경 상태를 표시합니다.

수정됨
추가됨
삭제됨

이는 git status를 확인하는 것과 비슷한 역할을 합니다. 커밋하기 전에 의도하지 않은 수정이 있는지 검토할 수 있습니다.

실험적 편집을 했지만 유지하지 않기로 했다면, push 전에 변경 사항을 폐기할 수 있습니다. 그러면 공유 Git 히스토리에 불필요한 변경이 남지 않습니다.

6. 저장소 및 브랜치 범위 프로젝트

스펙 우선 프로젝트는 특정 Git 저장소와 브랜치에 연결됩니다. 예를 들어 main 브랜치의 openapi.yaml을 기준으로 프로젝트를 만들 수 있습니다.

이 구조의 장점은 명확합니다.

스펙 파일 위치가 Git 저장소에 고정됩니다.
브랜치 기준으로 작업 범위가 분리됩니다.
API 계약 변경 이력이 Git 히스토리로 남습니다.
팀 권한을 프로젝트 설정과 연결해 관리할 수 있습니다.

스펙 우선 모드 설정 방법

공식 스크린샷이 포함된 가이드는 docs.apidog.com/spec-first-mode-beta-2058268m0에 있습니다.

기본 설정 흐름은 다음과 같습니다.

1. API 모듈에서 모드 전환

Apidog에서 API 모듈을 엽니다. 왼쪽 하단의 모드 토글에서 디자인 우선 모드에서 스펙 우선 모드로 전환합니다.

2. Git 제공업체 연결

사용 중인 Git 제공업체를 연결합니다.

GitHub: 직접 인증
GitLab: 직접 인증
Azure DevOps: 일반 Git 연결 사용

Azure DevOps의 경우 표준 Git 자격 증명으로 저장소를 연결합니다.

3. 저장소와 브랜치 선택

OpenAPI 스펙 파일이 있는 저장소를 선택합니다. 그런 다음 사용할 브랜치를 선택합니다. 일반적으로 main 또는 작업용 브랜치를 선택합니다.

4. 팀 권한 설정

프로젝트에 접근할 수 있는 팀원과 권한을 설정합니다. API 계약을 수정할 수 있는 사람과 읽기만 가능한 사람을 구분해 관리할 수 있습니다.

5. 스펙 파일 열기

편집기에서 openapi.yaml 또는 openapi.json을 엽니다. 왼쪽 개요를 사용해 paths, schemas, components를 탐색합니다.

6. YAML/JSON 수정

필요한 엔드포인트, 스키마, 응답 객체를 수정합니다. 작성 중 자동 완성과 유효성 검사를 활용합니다.

7. 변경 사항 검토 및 커밋

파일 변경 추적에서 수정 내용을 확인합니다. 문제가 없으면 명확한 커밋 메시지를 작성합니다.

예:

Add POST /invoices endpoint

또는

Update User schema response fields

8. 저장소에 푸시

커밋을 연결된 브랜치에 푸시합니다. 이후 동기화 상태 표시기를 확인해 저장소와 일치하는지 확인합니다.

전체 루프는 다음과 같습니다.

전환 -> 연결 -> 프로젝트 생성 -> 편집 -> 검토 -> 커밋 -> 푸시 -> 동기화 확인

일상적인 워크플로우 예시

스펙 우선 모드를 실제 업무에 적용하면 다음과 같은 흐름이 됩니다.

하루를 시작할 때 연결된 브랜치에서 최신 스펙을 pull 합니다.
왼쪽 개요에서 수정할 operation을 찾습니다.
YAML 또는 JSON을 직접 편집합니다.
자동 완성과 유효성 검사로 오류를 확인합니다.
변경 추적에서 수정 내용을 검토합니다.
커밋 메시지를 작성합니다.
저장소에 push 합니다.
팀원은 Git pull request에서 스펙 변경을 리뷰합니다.

예를 들어 인보이스 API에 사용할 스키마를 추가할 수 있습니다.

components:
  schemas:
    Invoice:
      type: object
      required: [id, amount, currency]
      properties:
        id:
          type: string
          format: uuid
        amount:
          type: integer
          description: Amount in the smallest currency unit
        currency:
          type: string
          example: USD
        status:
          type: string
          enum: [draft, sent, paid]

새 엔드포인트를 추가한다면 다음처럼 paths에 operation을 정의할 수 있습니다.

paths:
  /invoices:
    post:
      summary: Create an invoice
      operationId: createInvoice
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Invoice'
      responses:
        '201':
          description: Invoice created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'

이후 변경 사항을 커밋하고 push하면, API 스펙 변경은 일반 코드 변경처럼 Git 히스토리에 남습니다.

누가 스펙 우선 모드를 사용해야 하나요?

스펙 우선 모드는 다음 조건에 맞는 팀에 적합합니다.

OpenAPI 스펙을 코드처럼 관리하고 싶다.
API 계약 변경을 pull request에서 리뷰한다.
YAML/JSON 직접 편집에 익숙하다.
Git 브랜치, 커밋, push/pull 흐름을 이미 사용한다.
백엔드 또는 플랫폼 팀이 API 문서를 주도한다.
API 스펙을 서비스 코드와 함께 버전 관리하고 싶다.

반대로 다음 상황에서는 디자인 우선 모드가 더 적합할 수 있습니다.

비엔지니어도 API 설계에 자주 참여한다.
YAML 작성보다 폼 기반 UI가 더 편하다.
제품, 디자인, QA 등 혼합 팀이 시각적으로 API를 검토한다.
OpenAPI 문법에 익숙하지 않은 팀원이 많다.

결정 기준은 단순합니다. 팀이 이미 Git 중심으로 일한다면 스펙 우선 모드가 자연스럽습니다. 시각적 협업이 더 중요하다면 디자인 우선 모드가 더 빠를 수 있습니다.

더 자세한 선택 기준은 비교 게시물을 참고하십시오.

제한 사항 및 베타 노트

스펙 우선 모드는 베타 기능입니다. 따라서 실제 프로젝트에 적용하기 전에 다음 사항을 확인하는 것이 좋습니다.

기능과 동작은 피드백에 따라 변경될 수 있습니다.
GitHub와 GitLab은 직접 통합을 지원합니다.
Azure DevOps는 일반 Git 연결을 사용합니다.
특정 Git 제공업체나 내부 워크플로우가 있다면 먼저 테스트 저장소에서 검증하십시오.
메인 브랜치에 바로 적용하기보다 중요하지 않은 저장소나 테스트 브랜치에서 시작하는 것이 안전합니다.

스펙이 실제 Git 저장소와 동기화되므로 일반적인 Git 규율이 필요합니다.

커밋 전 변경 사항을 검토합니다.
의미 있는 커밋 메시지를 작성합니다.
의도하지 않은 수정은 push 전에 폐기합니다.
팀 브랜치 전략에 맞춰 작업합니다.

베타 기능의 장점은 초기 피드백이 제품 방향에 영향을 줄 수 있다는 점입니다. 팀 워크플로우에 필요한 기능이 빠져 있다면 피드백을 전달할 가치가 있습니다.

FAQ

스펙 우선 모드는 무료인가요?

스펙 우선 모드는 Apidog 내의 베타 기능입니다. 사용 가능 여부는 Apidog 플랜과 베타 접근 상태에 따라 달라질 수 있습니다. 가장 빠른 확인 방법은 API 모듈에서 모드 토글을 열어 현재 계정에서 사용할 수 있는지 확인하는 것입니다.

어떤 Git 제공업체가 지원되나요?

GitHub와 GitLab은 직접 통합으로 지원됩니다. Azure DevOps는 일반 Git 연결을 통해 사용할 수 있습니다. 이 연결은 표준 Git 자격 증명을 사용합니다.

디자인 우선 모드로 다시 전환할 수 있나요?

네. API 모듈 왼쪽 하단의 모드 토글에서 스펙 우선 모드와 디자인 우선 모드 사이를 전환할 수 있습니다.

어떤 파일 형식을 편집할 수 있나요?

OpenAPI 문서를 YAML 또는 JSON 형식으로 편집할 수 있습니다. 편집기는 OpenAPI 및 Swagger에 대한 구문 강조, 스키마 유효성 검사, 자동 완성을 제공합니다.

푸시되지 않은 편집 내용은 어떻게 되나요?

푸시되지 않은 편집 내용은 push 전까지 로컬 변경 사항으로 유지됩니다. 변경 사항은 수정됨, 추가됨, 삭제됨 상태로 추적됩니다. 원하지 않는 변경은 push 전에 폐기할 수 있으며, 그러면 공유 Git 히스토리에 반영되지 않습니다.

결론

Apidog 스펙 우선 모드는 OpenAPI 편집기와 Git 워크플로우를 하나로 묶습니다. YAML 또는 JSON으로 스펙을 직접 편집하고, 자동 파싱된 개요로 탐색하며, 작성 중 유효성 검사를 수행하고, GitHub, GitLab 또는 Azure DevOps와 양방향으로 동기화할 수 있습니다.

Git 기반으로 API 계약을 관리하는 팀이라면 다음 순서로 시작해 보십시오.

API 모듈에서 스펙 우선 모드를 활성화합니다.
테스트 저장소 또는 테스트 브랜치를 연결합니다.
작은 OpenAPI 변경 사항을 작성합니다.
변경 추적을 확인합니다.
커밋하고 push합니다.
팀의 기존 pull request 흐름에서 리뷰합니다.

준비가 되면 문서에서 스펙 우선 모드를 시도하고 실제 저장소에 연결해 워크플로우를 검증하십시오.

DEV Community