스펙 우선 방식으로 API를 구축한다면 선택지는 보통 두 가지로 나뉩니다. OpenAPI 파일을 실행 가능한 계약 검사로 바꿀 것인지, 아니면 API 설계, 목업, 테스트, CI 실행까지 한 흐름에서 처리할 것인지입니다. Specmatic과 Apidog CLI는 모두 스펙 우선 접근 방식을 따르지만, 해결하는 지점이 다릅니다. 이 글은 실제 API 계약 테스트 개념과 공식 OpenAPI 사양을 기준으로 두 도구를 구현 관점에서 비교합니다.
빠른 결론
Specmatic은 API 사양을 실행 가능한 계약으로 다룹니다. 사양에서 테스트를 생성하고, 실제 공급자 서비스를 대상으로 실행하며, 소비자 팀이 같은 계약을 기준으로 개발할 수 있도록 스텁도 제공합니다. 마이크로서비스 환경에서 소비자/공급자 계약 검증이 핵심 문제라면 잘 맞습니다.
Apidog는 스펙 우선 API 플랫폼입니다. OpenAPI 기반으로 API를 시각적으로 설계하고, 기능 테스트 시나리오를 만들고, 스키마 기반 목업을 생성하며, apidog run으로 CI에서 실행합니다. REST뿐 아니라 GraphQL, gRPC, WebSocket 등도 같은 워크플로에서 다룰 수 있습니다.
선택 기준은 간단합니다.
- 서비스 간 계약 위반을 잡는 것이 목표라면 Specmatic
- 설계, 목업, 기능 테스트, CI 실행을 한 흐름으로 묶고 싶다면 Apidog CLI
- 두 문제가 모두 있다면 OpenAPI를 공통 기준으로 두고 두 도구를 함께 사용
Specmatic이 해결하는 문제
Specmatic의 핵심은 “사양이 곧 계약이며, 계약은 실행 가능해야 한다”는 것입니다. OpenAPI, AsyncAPI, GraphQL, gRPC, WSDL 파일을 입력으로 사용하고, 사양에서 긍정/부정 테스트 시나리오를 자동으로 파생합니다.
대표적인 사용 흐름은 다음과 같습니다.
# 예시 흐름
# 1. OpenAPI 사양 준비
# 2. 실제 API 서버 실행
# 3. Specmatic으로 공급자 검증 실행
Specmatic이 강한 영역은 두 가지입니다.
1. 공급자 검증
Specmatic은 실행 중인 API가 사양과 일치하는지 확인합니다.
예를 들어 OpenAPI에 다음과 같은 응답이 정의되어 있다고 가정합니다.
paths:
/users/{id}:
get:
responses:
'200':
description: User detail
content:
application/json:
schema:
type: object
required:
- id
- email
properties:
id:
type: string
email:
type: string
구현체가 email 필드를 누락하거나 상태 코드를 바꾸면 계약 테스트가 실패해야 합니다. Specmatic은 이런 불일치를 자동으로 찾아내는 데 초점을 둡니다.
2. 계약 기반 서비스 가상화
동일한 사양을 스텁으로 실행할 수 있습니다. 소비자 팀은 실제 공급자 서비스가 완성되기 전에 이 스텁을 대상으로 개발할 수 있습니다.
이 방식의 장점은 명확합니다.
- 소비자와 공급자가 같은 OpenAPI 계약을 기준으로 작업
- 실제 서비스가 준비되지 않아도 통합 개발 가능
- 계약이 바뀌면 스텁과 검증 기준도 함께 바뀜
Specmatic은 GitHub에서 오픈 소스 코어를 제공하고, CI/CD에 맞는 CLI 중심 실행 모델을 갖습니다. 상용 레이어로 시각적 인터페이스용 Studio, 거버넌스 및 분석용 Insights도 제공합니다. 또한 AsyncAPI, GraphQL, gRPC, WSDL, Kafka, JMS, RabbitMQ 같은 이벤트 기반 백엔드까지 지원합니다.
단, Specmatic은 API 설계 화면이나 전체 기능 테스트 플랫폼이 되는 것을 목표로 하지 않습니다. 사양을 이미 작성하고 관리하는 팀이 그 사양을 강제하고 싶을 때 가장 적합합니다.
Apidog CLI가 해결하는 문제
Apidog CLI는 Apidog 플랫폼에서 만든 API 테스트를 CI/CD에서 실행하기 위한 명령줄 도구입니다. Apidog 앱에서 API를 설계하고 테스트 시나리오를 만든 뒤, 파이프라인에서는 apidog run으로 헤드리스 실행합니다. 옵션과 종료 코드 동작은 apidog run 명령어 참조를 참고하면 됩니다.
Apidog의 구현 흐름은 보통 다음과 같습니다.
- OpenAPI 기반으로 API 정의 작성
- 스키마에서 목업 서버 생성
- 요청 체인과 어설션으로 기능 테스트 구성
- 환경 변수와 테스트 데이터를 설정
- CI에서
apidog run실행 - 실패 시 빌드 중단
예시 CI 단계는 다음처럼 구성할 수 있습니다.
name: API tests
on:
push:
branches:
- main
jobs:
api-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Apidog tests
run: |
apidog run
실제 프로젝트에서는 Apidog 프로젝트, 환경, 토큰, 리포트 옵션 등을 함께 설정합니다. 자세한 흐름은 완전한 Apidog CLI 가이드에서 확인할 수 있습니다.
Apidog의 강점
1. 설계, 목업, 테스트를 한 곳에서 관리
Apidog에서는 OpenAPI 정의를 시각적으로 작성하고, 같은 스키마를 기준으로 목업과 테스트를 생성합니다. 즉, 설계와 검증이 분리되지 않습니다.
예를 들어 다음과 같은 API를 정의하면:
paths:
/orders:
post:
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- productId
- quantity
properties:
productId:
type: string
quantity:
type: integer
responses:
'201':
description: Order created
Apidog에서는 이 정의를 기반으로 다음 작업을 이어갈 수 있습니다.
- 프런트엔드 개발용 목업 응답 생성
-
POST /orders요청 테스트 작성 - 응답 상태 코드
201검증 - 응답 바디 필드 검증
- CI에서 반복 실행
스키마 우선 목업 흐름은 스키마 우선 목업 워크플로에서 더 자세히 볼 수 있습니다.
2. 계약 형태뿐 아니라 기능 흐름까지 테스트
Apidog는 단순히 “응답이 스키마와 일치하는가”만 확인하는 도구가 아닙니다. 요청을 연결하고, 이전 단계의 응답 값을 다음 요청에 넘기고, 데이터 기반 반복을 구성할 수 있습니다.
예를 들면 다음과 같은 시나리오를 만들 수 있습니다.
- 사용자 생성
- 생성된 사용자 ID 추출
- 해당 ID로 사용자 조회
- 응답의
email값 검증 - 사용자 삭제
- 삭제 후 조회 시
404확인
이런 흐름은 순수 계약 검사보다 E2E API 기능 테스트에 더 가깝습니다.
3. 여러 프로토콜을 같은 흐름으로 실행
Apidog는 REST, GraphQL, gRPC, SOAP, WebSocket을 지원합니다. REST API뿐 아니라 gRPC 서비스나 WebSocket 이벤트도 함께 테스트해야 하는 팀이라면 테스트 도구를 여러 개로 나누지 않아도 됩니다.
4. CI에서 실행 가능
apidog run은 CI/CD에서 실행하기 위한 명령입니다. 테스트 실패 시 적절한 종료 코드를 반환하고, 파이프라인에서 읽을 수 있는 보고서를 생성할 수 있습니다. 따라서 GitHub Actions, GitLab CI, Jenkins 같은 환경에 연결하기 쉽습니다.
단, Apidog는 Pact 스타일의 소비자 주도 계약 브로커가 아닙니다. OpenAPI 스키마 검증과 기능 테스트 실행에는 강하지만, 독립된 소비자/공급자 저장소 간 공식 계약 브로커 핸드셰이크가 필요하다면 Specmatic 쪽이 더 적합합니다.
비교 표
| 영역 | Specmatic | Apidog CLI |
|---|---|---|
| 주요 초점 | 코드형 계약, 공급자 검증, 계약 기반 스텁 | 스펙 우선 설계, 목업, 기능 테스트, CI 실행 |
| 테스트 생성 | 사양에서 긍정/부정 테스트 자동 생성 | 시각적 시나리오 구성, 스키마 검증 내장 |
| 공급자/소비자 계약 검증 | 핵심 강점 | 스키마 검증 중심, 계약 브로커는 아님 |
| 목업 | 계약 기반 서비스 가상화 | OpenAPI 설계 기반 스키마 목업 서버 |
| 프로토콜 | OpenAPI, AsyncAPI, GraphQL, gRPC, WSDL, Kafka, JMS 등 | REST, GraphQL, gRPC, SOAP, WebSocket |
| 인터페이스 | CLI + 상용 Studio/Insights | 시각적 앱 + apidog run CLI |
| 기능/E2E 흐름 | 계약 시나리오 중심 | 요청 체인, 데이터 기반 실행, 어설션 |
| 오픈 소스 | 코어 오픈 소스 | 무료 티어 제공, 플랫폼은 상업적 |
| 적합한 용도 | 독립 서비스 간 계약 무결성 유지 | API 라이프사이클 전반의 설계, 목업, 테스트 |
언제 Specmatic을 선택할까?
다음 조건에 해당하면 Specmatic이 적합합니다.
- 여러 팀이 각자 서비스를 소유한다
- 서비스가 독립적으로 배포된다
- 배포 후 계약 불일치가 자주 발생한다
- API, 이벤트, gRPC 등 여러 통신 방식에서 계약을 강제해야 한다
- 사양에서 자동으로 계약 테스트를 생성하고 싶다
예를 들어 주문 서비스와 결제 서비스가 서로 다른 팀에 의해 배포되고, 응답 필드 변경 하나가 소비자 장애로 이어진다면 Specmatic의 공급자 검증과 계약 기반 스텁이 유용합니다.
언제 Apidog CLI를 선택할까?
다음 조건에 해당하면 Apidog CLI가 적합합니다.
- API 설계부터 테스트까지 하나의 도구에서 처리하고 싶다
- 백엔드 구현 전 프런트엔드용 목업이 필요하다
- OpenAPI 기반으로 기능 테스트를 구성하고 싶다
- 요청 간 데이터 전달이 필요한 시나리오가 있다
- GitHub Actions, GitLab CI, Jenkins에서 API 테스트를 실행하고 싶다
- REST 외에 gRPC, WebSocket 등도 함께 테스트한다
예를 들어 새 API를 만들 때 다음 흐름을 한 곳에서 진행하고 싶다면 Apidog가 적합합니다.
OpenAPI 설계
→ 목업 서버 생성
→ 프런트엔드 병렬 개발
→ 기능 테스트 작성
→ CI에서 apidog run 실행
→ 실패 시 배포 차단
설계, 목업, 검증이 함께 동작하는 방식은 계약 테스트 및 목업 서버 가이드에서도 확인할 수 있습니다.
두 도구를 함께 사용하는 패턴
두 도구는 경쟁 관계로만 볼 필요가 없습니다. OpenAPI 파일을 공통 진실의 원천으로 두고 역할을 나누면 됩니다.
권장 패턴은 다음과 같습니다.
- Apidog에서 OpenAPI 사양 설계
- Apidog 목업 서버로 소비자 개발 지원
- Apidog에서 기능 테스트 시나리오 작성
- CI에서
apidog run으로 기능 테스트 실행 - 서비스 간 공식 계약 검증이 필요한 곳에 Specmatic 추가
- Specmatic으로 공급자 검증 및 계약 기반 스텁 운영
이렇게 하면 Apidog는 API 라이프사이클의 설계, 목업, 기능 테스트를 담당하고, Specmatic은 팀 간 계약 검증과 가상화를 담당합니다.
자주 묻는 질문
Apidog는 Specmatic의 대안인가요?
일부 영역에서는 대안이 될 수 있지만, 완전한 1:1 대체는 아닙니다.
API를 설계하고, 목업하고, 기능 테스트를 작성하고, CI에서 실행하는 것이 목적이라면 Apidog가 더 넓은 영역을 다룹니다. 반대로 소비자/공급자 간 계약 검증과 계약 기반 스텁이 핵심이면 Specmatic이 더 직접적인 선택입니다.
Apidog CLI는 계약 테스트를 수행하나요?
Apidog는 테스트 실행 중 OpenAPI 스키마를 기준으로 응답을 검증할 수 있습니다. 따라서 사양과 구현 간 구조적 불일치를 찾는 데 사용할 수 있습니다.
다만 별도의 소비자 및 공급자 저장소 사이에서 Pact 스타일 계약 브로커 역할을 하지는 않습니다. 스키마 검증과 브로커 스타일 계약의 차이는 API 계약 테스트란 무엇인가 글을 참고하세요.
CI/CD에는 어떤 도구가 더 잘 맞나요?
둘 다 CI/CD에서 헤드리스로 실행할 수 있습니다.
- Specmatic: 사양에서 계약 테스트를 자동 생성하고 공급자를 검증
- Apidog CLI: Apidog에서 만든 기능 테스트 시나리오를
apidog run으로 실행
CI 게이트의 목적이 “서비스 간 계약 검증”이면 Specmatic이 적합합니다. 목적이 “API 기능 테스트 전체 실행”이면 Apidog CLI가 적합합니다.
테스트 코드를 직접 작성해야 하나요?
대부분의 경우 많이 작성하지 않아도 됩니다.
Specmatic은 사양에서 계약 테스트를 생성합니다. Apidog는 시각적 시나리오 빌더, 어설션, 데이터 기반 반복을 통해 테스트를 구성합니다. 둘 다 코드 우선 테스트 프레임워크보다 직접 작성해야 하는 테스트 코드를 줄여줍니다.
결론
Specmatic과 Apidog CLI는 모두 사양에서 출발하지만 초점이 다릅니다. Specmatic은 코드형 계약에 강합니다. 공급자를 사양에 대해 검증하고, 소비자를 위해 계약 기반 스텁을 제공합니다. Apidog CLI는 더 넓은 API 라이프사이클을 다룹니다. 설계, 목업, 기능 테스트, CI 실행을 하나의 흐름으로 연결합니다.
팀의 병목이 “서비스들이 서로의 계약을 계속 깨뜨린다”라면 Specmatic을 우선 검토하세요. 병목이 “API를 더 빠르게 설계하고, 목업하고, 테스트하고, CI에 연결해야 한다”라면 Apidog CLI가 더 적합합니다. 두 문제가 모두 있다면 OpenAPI를 공통 기준으로 두고 두 도구를 함께 사용하는 방식이 현실적입니다.
스펙 우선 설계, 목업, CI 준비 테스트 워크플로를 하나의 플랫폼에서 시작하려면 Apidog를 다운로드하거나 Apidog에서 API 라이프사이클 전반의 기능을 확인해 보세요.
Top comments (0)