Rihpig

Posted on Jun 2 • Originally published at apidog.com

Apidog 스펙 우선 vs 디자인 우선: 어떤 모드를 사용해야 할까요?

Apidog의 API 모듈에서는 동일한 API 계약을 두 가지 방식으로 작성할 수 있습니다. 하나는 시각적 양식으로 엔드포인트와 스키마를 설계하는 디자인-우선 모드이고, 다른 하나는 Git에 연결된 YAML/JSON 사양 파일을 직접 편집하는 사양-우선 모드입니다. 두 방식 모두 유효한 OpenAPI를 생성하지만, 팀의 협업 방식과 Git 사용 습관에 따라 적합한 기본값이 달라집니다.

지금 Apidog 사용해 보기

이 글에서는 Apidog에서 디자인-우선과 사양-우선 중 어떤 모드를 선택해야 하는지 구현 관점에서 정리합니다. 각 모드의 작업 방식, Git 연동 방식, 팀 유형별 선택 기준, 그리고 모드 전환 시 확인할 사항을 다룹니다. API 모듈의 왼쪽 하단 토글로 두 모드 사이를 전환할 수 있으므로 선택은 영구적이지 않습니다. 다만 올바른 기본값을 정하면 API 설계와 리뷰 과정의 마찰을 줄일 수 있습니다.

두 가지 접근 방식의 핵심 차이

두 방식 모두 같은 원칙을 따릅니다.

구현 코드를 작성하기 전에 API 계약을 먼저 정의한다.

API 계약은 엔드포인트, 요청/응답 스키마, 파라미터, 예시, 오류 구조를 포함하는 진실의 원천입니다. 이후 목업, 테스트, 문서, 클라이언트 연동은 이 계약을 기준으로 만들어집니다.

차이는 계약을 작성하는 인터페이스입니다.

디자인-우선 모드

양식, 드롭다운, 스키마 트리 같은 시각적 UI로 API를 설계합니다. OpenAPI 문법을 직접 작성하지 않아도 됩니다.
사양-우선 모드

YAML 또는 JSON 형식의 OpenAPI/Swagger 파일을 직접 작성합니다. 사양 파일을 소스 코드처럼 Git에서 관리합니다.

주의할 점은 이 둘이 코드-우선 API 개발과 다르다는 것입니다. 코드-우선은 구현 코드의 주석이나 데코레이터에서 사양을 생성합니다. Apidog의 두 모드는 모두 계약을 코드보다 먼저 다룹니다. 차이는 계약을 양식으로 편집하느냐, 사양 파일로 편집하느냐입니다.

사양을 버전 관리되는 아티팩트로 다루는 방식이 궁금하다면 Git-native API 워크플로우를 참고하십시오.

Apidog 디자인-우선 모드 사용 방식

디자인-우선 모드는 시각적 API 디자이너입니다. OpenAPI 문법을 직접 작성하지 않고 다음 순서로 API 계약을 구성합니다.

HTTP 메서드를 선택합니다.
경로를 입력합니다.
경로 파라미터와 쿼리 파라미터를 추가합니다.
요청 바디 스키마를 트리 편집기로 정의합니다.
응답 스키마와 상태 코드를 추가합니다.
예시 데이터를 첨부합니다.
Apidog가 내부적으로 OpenAPI 사양을 생성합니다.

예를 들어 GET /users/{id} 엔드포인트를 설계한다면 디자인-우선 모드에서는 다음 항목을 UI에서 순서대로 입력합니다.

Method: GET
Path: /users/{id}
Path parameter: id
Response 200: 사용자 객체 스키마
Response 404: 공통 Error 스키마

이 방식의 장점은 OpenAPI 문법을 몰라도 계약을 안전하게 만들 수 있다는 점입니다. 잘못된 괄호, 잘못된 타입 선언, 누락된 필드 같은 오류를 줄일 수 있습니다. 공통 Error 스키마, 인증 헤더, 재사용 가능한 응답 구조도 UI에서 선택해 적용할 수 있습니다.

디자인-우선 모드는 특히 다음 상황에 적합합니다.

PM, QA, 백엔드, 프론트엔드가 함께 API를 리뷰해야 하는 경우
팀원 간 OpenAPI 숙련도 차이가 큰 경우
새 API를 빠르게 설계해야 하는 경우
원시 YAML보다 구조화된 변경 사항을 리뷰하고 싶은 경우

단점도 있습니다. OpenAPI에 이미 익숙한 엔지니어라면 양식 기반 편집이 오히려 느리게 느껴질 수 있습니다. 머릿속에 있는 사양을 바로 YAML로 작성하고 싶은 팀이라면 사양-우선 모드가 더 자연스럽습니다.

Apidog 사양-우선 모드 사용 방식

사양-우선 모드는 현재 베타 버전이며, OpenAPI 또는 Swagger 사양을 YAML/JSON으로 직접 작성하는 방식입니다. Apidog는 IDE 스타일의 코드 편집기를 제공하고, 사양 파일은 Git 저장소와 동기화할 수 있습니다.

이 모드에서는 다음과 같은 방식으로 작업합니다.

GitHub, GitLab 또는 Azure DevOps 저장소를 연결합니다.
OpenAPI/Swagger 사양 파일을 선택합니다.
Apidog 코드 편집기에서 YAML 또는 JSON을 수정합니다.
인라인 유효성 검사와 자동 완성으로 오류를 확인합니다.
Apidog에서 변경 사항을 커밋하고 푸시합니다.
또는 로컬 코드 편집기에서 수정한 뒤 Git으로 푸시하고 Apidog로 다시 동기화합니다.

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

paths:
  /users/{id}:
    get:
      summary: 사용자 조회
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 사용자 조회 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: 사용자를 찾을 수 없음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

편집기는 OpenAPI 및 Swagger 스키마에 맞춰 다음 기능을 제공합니다.

구문 강조
인라인 유효성 검사
자동 완성
경로 및 컴포넌트 자동 파싱
왼쪽 사이드바 기반 사양 탐색
Git 동기화 상태 표시

핵심은 양방향 Git 동기화입니다. Apidog에서 수정한 사양을 커밋하고 푸시할 수 있고, 반대로 로컬 IDE에서 수정한 사양을 Git으로 푸시한 뒤 Apidog로 가져올 수도 있습니다. 즉, Apidog가 별도의 진실의 원천이 되는 것이 아니라 Git 저장소에 있는 동일한 사양 파일을 편집하는 창이 됩니다.

설정 방법은 사양-우선 모드 문서에서 확인할 수 있습니다.

API 사양을 코드 아티팩트처럼 관리하는 방식에 익숙하다면 코드형 API 사양도 참고하십시오.

디자인-우선 vs 사양-우선 비교

두 모드는 모두 OpenAPI를 생성하고, 목업, 테스트, 문서화에 사용할 수 있습니다. 차이는 작성 방식과 Git 워크플로우입니다.

항목	디자인-우선 모드	사양-우선 모드
편집 방식	시각적 양식, 스키마 트리	YAML/JSON 코드 편집기
사양 형식	OpenAPI 자동 생성	OpenAPI/Swagger 직접 작성
Git 워크플로우	Apidog 내 브랜치 지원	GitHub, GitLab, Azure DevOps와 양방향 동기화
유효성 검사	양식 입력 단계에서 강제	인라인 구문 검사 및 자동 완성
탐색 방식	엔드포인트 목록, 폴더	자동 파싱된 경로 및 컴포넌트 개요
학습 곡선	낮음	높음
적합한 팀	다양한 역할이 함께 API를 설계하는 팀	사양을 코드처럼 관리하는 엔지니어링 팀

어떤 모드를 선택해야 하나

디자인-우선 모드를 선택할 때

다음 조건에 해당한다면 디자인-우선 모드가 기본값으로 적합합니다.

팀원 모두가 OpenAPI 문법에 익숙하지 않다.
PM, QA, 프론트엔드, 백엔드가 함께 API 계약을 검토한다.
새 API를 빠르게 설계해야 한다.
YAML 문법 오류보다 API 구조 자체에 집중하고 싶다.
시각적으로 요청/응답 스키마를 구성하는 방식이 더 편하다.

실무에서는 새 엔드포인트를 만들 때 다음 흐름으로 진행할 수 있습니다.

디자인-우선 모드에서 엔드포인트 초안을 만든다.
요청/응답 스키마를 추가한다.
예시 데이터를 작성한다.
팀원이 구조화된 변경 사항을 리뷰한다.
목업 또는 테스트에 연결한다.

이 방식은 API 설계 초기 단계에서 빠르게 합의점을 찾는 데 유리합니다.

사양-우선 모드를 선택할 때

다음 조건에 해당한다면 사양-우선 모드가 더 적합합니다.

OpenAPI 파일이 이미 Git 저장소에 있다.
API 변경 사항을 풀 리퀘스트에서 리뷰한다.
CI에서 사양 린팅이나 검증을 실행한다.
서비스 코드 옆에 API 계약을 함께 보관하고 싶다.
YAML/JSON 직접 편집이 더 빠르다.
단일 정규 사양 파일을 여러 도구에서 공유한다.

사양-우선 모드의 일반적인 작업 흐름은 다음과 같습니다.

저장소의 OpenAPI 파일을 Apidog에 연결한다.
Apidog 또는 로컬 IDE에서 사양을 수정한다.
변경 사항을 Git에 커밋한다.
풀 리퀘스트에서 API 변경 사항을 리뷰한다.
CI에서 사양 유효성 검사 또는 린팅을 실행한다.
변경된 계약을 기준으로 구현, 테스트, 문서를 업데이트한다.

이 방식은 API 계약을 서비스 코드와 동일한 수준의 버전 관리 대상으로 다루는 팀에 적합합니다.

실용적인 선택 전략

두 모드는 경쟁 관계가 아니라 동일한 API 계약을 보는 두 가지 편집 표면입니다. 따라서 다음과 같은 단계적 접근이 가능합니다.

초기 설계 단계

디자인-우선 모드로 빠르게 엔드포인트와 스키마를 만든다.
팀 합의 단계

UI에서 요청/응답 구조와 예시를 리뷰한다.
성숙 단계

API가 안정되면 사양-우선 모드로 전환해 Git 기반 리뷰를 강화한다.
운영 단계

OpenAPI 파일을 서비스 코드와 함께 관리하고 CI 검증에 연결한다.

즉, 처음부터 하나의 모드에 고정할 필요는 없습니다. 팀의 현재 협업 방식에 맞는 모드를 기본값으로 선택하고, 필요할 때 전환하면 됩니다.

모드 전환 방법

Apidog에서 모드를 전환하는 절차는 간단합니다.

Apidog 프로젝트를 엽니다.
API 모듈로 이동합니다.
왼쪽 하단의 모드 전환기를 찾습니다.
디자인-우선 또는 사양-우선 모드를 선택합니다.
동일한 API 계약이 선택한 편집 방식으로 표시되는지 확인합니다.

전환 시 확인할 사항은 다음과 같습니다.

기본 계약은 동일하므로 엔드포인트, 스키마, 예시는 유지됩니다.
편집 표면만 바뀌며 API를 다시 만들 필요는 없습니다.
사양-우선 모드에서 Git 동기화를 사용하려면 먼저 저장소를 연결해야 합니다.
Git 연결 후 동기화 표시기로 커밋 및 푸시 상태를 확인하십시오.
사양-우선 모드는 베타 버전이므로 중요한 프로덕션 계약에 적용하기 전에 테스트 프로젝트에서 동작을 확인하는 것이 좋습니다.

FAQ

사양-우선은 계약-우선과 같은 의미인가요?

실무적으로는 거의 같습니다. 사양-우선과 계약-우선은 모두 구현 전에 API 사양을 먼저 작성하고, 그 사양을 진실의 원천으로 삼는다는 의미입니다. Apidog의 사양-우선 모드는 Git에 동기화된 OpenAPI 또는 Swagger 파일을 계약으로 사용하는 계약-우선 워크플로우입니다.

사양-우선 모드는 GitLab 및 Azure DevOps와 함께 작동하나요?

네. 사양-우선 모드는 GitHub 및 GitLab과의 양방향 Git 동기화를 지원합니다. Azure DevOps는 일반 Git 연결을 통해 사용할 수 있으므로 Azure에서 호스팅되는 저장소의 사양 파일도 동기화할 수 있습니다.

디자인-우선에서 사양-우선으로 전환하면 작업을 잃나요?

아니요. 두 모드는 동일한 기본 API 계약을 읽고 씁니다. API 모듈의 왼쪽 하단 토글로 전환해도 엔드포인트, 스키마, 예시는 유지됩니다. 데이터를 바꾸는 것이 아니라 편집기를 바꾸는 것입니다.

어떤 모드부터 시작하는 것이 좋나요?

팀에 OpenAPI 숙련도가 다양하다면 디자인-우선 모드부터 시작하는 것이 좋습니다. 반대로 팀이 이미 OpenAPI 파일을 Git에서 관리하고 풀 리퀘스트 기반으로 리뷰한다면 사양-우선 모드가 더 자연스럽습니다.

결론

Apidog의 디자인-우선 모드와 사양-우선 모드는 모두 API 계약을 코드보다 먼저 정의하기 위한 방식입니다.

빠른 설계, 쉬운 온보딩, 시각적 리뷰가 중요하다면 디자인-우선 모드
Git 기반 리뷰, CI 검증, 사양 파일 직접 관리가 중요하다면 사양-우선 모드

API 모듈을 열고 다음 엔드포인트를 두 방식으로 모두 만들어 보십시오. 생성되는 계약은 동일합니다. 팀이 이미 일하는 방식과 더 잘 맞는 편집 표면을 기본값으로 선택하면 됩니다.

DEV Community