DEV Community

Cover image for 스펙매틱이란 무엇인가요?
Rihpig
Rihpig

Posted on • Originally published at apidog.com

스펙매틱이란 무엇인가요?

OpenAPI 파일은 최신인데 실행 중인 서비스가 사양과 달라지고 있다면, Specmatic으로 그 차이를 자동으로 잡을 수 있습니다. Specmatic은 API 사양을 실행 가능한 계약으로 취급하고, 같은 사양으로 실제 서비스를 테스트하거나 스텁 서버를 실행합니다. 이 글에서는 Specmatic을 OpenAPI 계약 테스트에 적용하는 방법, 예제 기반 테스트와의 차이, CI에 넣는 방식, 그리고 Apidog의 API 계약 테스트 같은 플랫폼 접근 방식과의 차이를 정리합니다. 기반 사양 형식은 OpenAPI Specification입니다.

지금 Apidog를 사용해 보세요

Specmatic이란 무엇인가

Specmatic은 계약 기반 개발을 위한 오픈 소스 도구입니다. 핵심은 단순합니다.

API 사양을 문서가 아니라 실행 가능한 계약으로 사용합니다.

OpenAPI 파일을 Specmatic에 전달하면 다음 두 가지 작업을 할 수 있습니다.

  • 사양을 기준으로 실제 API 서비스를 테스트합니다.
  • 같은 사양을 기준으로 스텁 서버를 실행합니다.

즉, 하나의 OpenAPI YAML 또는 JSON 파일이 다음 역할을 모두 수행합니다.

OpenAPI Spec
├── Provider Contract Test
└── Consumer Stub Server
Enter fullscreen mode Exit fullscreen mode

별도의 테스트 정의와 별도의 목 서버 설정을 동기화할 필요가 없습니다. 사양이 변경되면 테스트와 스텁도 같은 계약을 기준으로 동작합니다.

Specmatic은 OpenAPI뿐 아니라 AsyncAPI, GraphQL, gRPC, WSDL, Avro 같은 형식도 지원합니다. 다만 대부분의 팀은 OpenAPI YAML 또는 JSON 파일에서 시작하는 것이 가장 현실적입니다.

CLI 또는 Docker 이미지로 실행할 수 있으므로 로컬 개발 환경과 CI 파이프라인에 쉽게 넣을 수 있습니다.

계약 테스트 vs 예제 기반 테스트

일반적인 API 테스트는 예제 기반입니다. 개발자가 요청을 하나 작성하고, 응답 상태 코드나 특정 필드를 직접 검증합니다.

예를 들면 다음과 같습니다.

curl http://localhost:8080/users/1
Enter fullscreen mode Exit fullscreen mode

그리고 테스트 코드에서 다음과 같이 검증합니다.

expect(response.status).toBe(200);
expect(response.body.id).toBe(1);
expect(response.body.name).toBeDefined();
Enter fullscreen mode Exit fullscreen mode

이 방식은 명확하지만, 다음 문제가 있습니다.

  • 테스트 케이스를 직접 계속 작성해야 합니다.
  • 사양에 있는 모든 경로를 커버하기 어렵습니다.
  • OpenAPI 문서와 테스트가 따로 놀 수 있습니다.
  • 스키마 변경 시 테스트 누락이 발생하기 쉽습니다.

계약 테스트는 접근 방식이 다릅니다.

Specmatic은 OpenAPI 사양을 읽고 다음을 자동으로 확인합니다.

  • 정의된 경로가 실제 서비스에서 동작하는가
  • 응답 상태 코드가 사양과 일치하는가
  • 응답 바디가 스키마와 일치하는가
  • 필수 필드가 빠지지 않았는가
  • 잘못된 요청이 사양에 맞게 거부되는가

즉, 단언문을 하나씩 작성하는 대신 사양 자체가 단언문이 됩니다.

측면 예제 기반 테스트 Specmatic 계약 테스트
진실의 원천 직접 작성한 테스트 케이스 OpenAPI 사양
유지 관리 대상 요청, 응답, 단언문 API 사양
커버리지 작성한 케이스만 사양에 선언된 작업
드리프트 감지 수동 확인 자동 실패
실패 의미 특정 예제가 깨짐 서비스가 계약과 불일치

계약 테스트에도 여러 방식이 있습니다. Pact는 소비자 주도 계약 테스트에 가깝습니다. 소비자가 기대치를 브로커에 게시하고, 공급자는 그 기대치를 검증합니다.

Specmatic은 계약 주도 방식입니다. OpenAPI 같은 공유 사양을 단일 계약으로 보고, 그 계약을 기준으로 공급자를 검증하고 소비자에게 스텁을 제공합니다.

따라서 Specmatic은 Pact 브로커가 아닙니다. 소비자가 게시한 팩트를 관리하지 않습니다. 더 넓은 비교가 필요하다면 API 계약 테스트 및 목 도구를 참고할 수 있습니다.

Specmatic 실행 방법

Specmatic은 네이티브 CLI 또는 Docker로 실행할 수 있습니다. CI에서는 Docker 방식이 가장 간단합니다.

1. 계약 테스트 실행

실행 중인 API 서버가 있다고 가정합니다.

API Server: http://localhost:8080
OpenAPI Spec: api.yaml
Enter fullscreen mode Exit fullscreen mode

네이티브 CLI로 실행하면 다음과 같습니다.

specmatic test api.yaml --testBaseURL=http://localhost:8080
Enter fullscreen mode Exit fullscreen mode

Docker로 실행하려면 다음처럼 현재 디렉터리를 컨테이너에 마운트합니다.

docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
  test api.yaml --testBaseURL=http://host.docker.internal:8080
Enter fullscreen mode Exit fullscreen mode

Specmatic은 api.yaml을 읽고 다음 작업을 수행합니다.

  1. 사양에 정의된 엔드포인트를 찾습니다.
  2. 요청을 생성합니다.
  3. 실제 서비스로 요청을 보냅니다.
  4. 응답을 OpenAPI 스키마와 비교합니다.
  5. 불일치가 있으면 테스트를 실패시킵니다.

테스트 실패는 둘 중 하나를 의미합니다.

  • 실제 서비스 구현이 사양과 다릅니다.
  • 사양이 실제 의도와 다르게 작성되었습니다.

따라서 수정 대상은 서비스 코드 또는 OpenAPI 사양입니다.

2. 사양을 스텁 서버로 실행하기

소비자 팀이 아직 실제 백엔드를 기다리고 있다면 같은 사양으로 스텁 서버를 실행할 수 있습니다.

specmatic stub api.yaml --port=9000
Enter fullscreen mode Exit fullscreen mode

이제 클라이언트나 프론트엔드는 다음 주소를 대상으로 개발할 수 있습니다.

http://localhost:9000
Enter fullscreen mode Exit fullscreen mode

Specmatic은 사양에 맞는 응답을 생성합니다. 구체적인 응답 예제가 필요하면 사양 옆에 _examples 디렉터리를 두고 요청/응답 예제를 저장할 수 있습니다. 요청이 예제와 일치하면 스텁은 해당 예제를 반환합니다.

이 방식은 다음 상황에서 유용합니다.

  • 백엔드 구현 전 프론트엔드 개발
  • 외부 API 의존성 제거
  • 통합 테스트에서 안정적인 응답 사용
  • 소비자 팀과 공급자 팀의 병렬 개발

여러 도구의 스텁 및 목 옵션을 비교하려면 계약 테스트 및 목 서버 개요를 참고할 수 있습니다.

3. 기존 서비스에서 사양 생성하기

이미 동작하는 서비스가 있지만 OpenAPI 사양이 없다면 Specmatic을 프록시처럼 둘 수 있습니다. 실제 요청과 응답 트래픽을 캡처하고, 이를 기반으로 OpenAPI 문서와 예제 파일을 생성할 수 있습니다.

이 방식은 다음과 같은 레거시 API에 특히 유용합니다.

Client → Specmatic Proxy → Existing API
Enter fullscreen mode Exit fullscreen mode

캡처된 실제 트래픽을 출발점으로 삼으면 빈 OpenAPI 파일을 처음부터 작성하는 부담을 줄일 수 있습니다.

하나의 사양을 테스트와 스텁으로 함께 사용하기

Specmatic의 핵심 가치는 동일한 사양을 양쪽에서 실행한다는 점입니다.

공급자 팀은 CI에서 다음을 실행합니다.

specmatic test api.yaml --testBaseURL=http://service-under-test:8080
Enter fullscreen mode Exit fullscreen mode

소비자 팀은 로컬에서 다음을 실행합니다.

specmatic stub api.yaml --port=9000
Enter fullscreen mode Exit fullscreen mode

이렇게 하면 양쪽 모두 같은 계약을 기준으로 작업합니다.

Provider CI
  └── specmatic test api.yaml

Consumer Local Dev
  └── specmatic stub api.yaml
Enter fullscreen mode Exit fullscreen mode

사양이 오래된 문서로 남지 않고 실제 개발 루프에 들어갑니다. 이것이 단순한 목 데이터와 계약 기반 스텁의 차이입니다. 워크플로우를 설계하기 전에 API 스터빙 vs 목킹의 차이를 이해하는 것도 도움이 됩니다.

하위 호환성 검사

Specmatic은 하위 호환성 검사도 지원합니다.

backward-compatibility-check 명령은 새 사양 버전으로 스텁을 시작하고, 이전 사양 버전에서 생성한 테스트를 새 스텁에 대해 실행합니다.

개념적으로는 다음 흐름입니다.

Old Spec → Generate Tests
New Spec → Start Stub
Tests run against New Stub
Enter fullscreen mode Exit fullscreen mode

이전 소비자가 기대하던 동작이 새 사양에서 깨졌다면 릴리스 전에 확인할 수 있습니다.

마이크로서비스 환경에서는 특히 중요합니다.

  • 서비스가 독립적으로 배포됩니다.
  • 소비자와 공급자의 배포 시점이 다릅니다.
  • API 변경이 즉시 모든 소비자에게 반영되지 않습니다.
  • 호환성 깨짐을 사전에 감지해야 합니다.

이 접근은 양방향 계약 테스트에서 다루는 더 넓은 아이디어와 연결됩니다.

CI에 넣는 예시

Specmatic은 CLI 기반이므로 CI에 넣기 쉽습니다. 예를 들어 GitHub Actions에서는 다음처럼 구성할 수 있습니다.

name: Contract Test

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  contract-test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Start API service
        run: |
          docker compose up -d api

      - name: Run Specmatic contract tests
        run: |
          docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
            test api.yaml --testBaseURL=http://host.docker.internal:8080
Enter fullscreen mode Exit fullscreen mode

실제 환경에서는 API 서비스가 준비될 때까지 대기하는 단계가 필요할 수 있습니다.

until curl -f http://localhost:8080/health; do
  sleep 2
done
Enter fullscreen mode Exit fullscreen mode

CI에서 중요한 원칙은 간단합니다.

  • API 코드 변경 시 계약 테스트를 실행합니다.
  • OpenAPI 사양 변경 시에도 계약 테스트를 실행합니다.
  • 계약 불일치가 있으면 빌드를 실패시킵니다.

Specmatic이 적합한 경우

Specmatic은 다음 조건에 잘 맞습니다.

  • OpenAPI, AsyncAPI, GraphQL, gRPC 사양을 실제로 관리하고 있습니다.
  • 공급자와 소비자 서비스가 분리되어 있습니다.
  • API 사양 드리프트를 수동 리뷰가 아니라 자동 테스트로 잡고 싶습니다.
  • CLI와 CI 중심 워크플로우에 익숙합니다.
  • 시각적 도구보다 계약 엔진 자체가 더 중요합니다.

반대로 다음 경우에는 덜 적합할 수 있습니다.

  • OpenAPI 사양을 거의 관리하지 않습니다.
  • API 설계, 디버깅, 문서화, 협업을 하나의 UI에서 처리하고 싶습니다.
  • 개발자가 터미널 중심 도구보다 시각적 워크스페이스를 선호합니다.
  • 임시 API 테스트와 팀 협업 기능이 더 중요합니다.

Specmatic은 범위가 명확합니다. 계약 테스트와 계약 기반 스텁에 집중합니다.

Specmatic과 Apidog의 차이

Apidog도 스키마 기반 접근을 사용합니다. OpenAPI 사양을 읽고, 응답을 스키마에 대해 검증하며, 코드 없이 OpenAPI 스키마에서 목 서버를 실행할 수 있습니다.

차이는 범위입니다.

Specmatic은 CLI 중심의 계약 테스트 도구입니다.

Specmatic
├── Contract Test
├── Stub Server
└── CI Workflow
Enter fullscreen mode Exit fullscreen mode

Apidog는 시각적 API 워크스페이스입니다.

Apidog
├── API Design
├── API Debugging
├── Schema Validation
├── Mock Server
├── Test Collection
└── Documentation
Enter fullscreen mode Exit fullscreen mode

따라서 팀이 이미 OpenAPI 파일을 Git에서 관리하고 CI에 계약 검사를 넣고 싶다면 Specmatic이 잘 맞습니다.

반대로 API 설계, 테스트, 목킹, 문서화를 한 곳에서 처리하고 싶다면 Apidog 같은 플랫폼 접근 방식이 더 편할 수 있습니다.

워크스페이스 안에서 사양으로부터 실행 가능한 테스트를 만들고 싶다면 OpenAPI 사양에서 API 테스트 컬렉션 생성 방식을 확인할 수 있습니다.

단, Apidog도 Pact 스타일의 소비자 주도 계약 브로커는 아닙니다. 팀에 Pact 브로커가 반드시 필요하다면 별도의 도구를 검토해야 합니다.

자주 묻는 질문

Specmatic은 무료인가요?

네. 핵심 계약 엔진은 오픈 소스이며 CLI 또는 Docker로 무료 사용할 수 있습니다. 상업용 오퍼링도 있지만, OpenAPI 사양에서 계약 테스트와 스텁 서버를 실행하는 기본 흐름은 비용 없이 시작할 수 있습니다. 최신 라이선스와 유료 기능은 공식 사이트와 GitHub를 확인하는 것이 좋습니다.

Specmatic은 OpenAPI에서만 작동하나요?

아니요. OpenAPI가 가장 일반적인 진입점이지만, Specmatic은 AsyncAPI, GraphQL, gRPC, WSDL, Avro 같은 형식도 지원합니다. 형식은 달라도 모델은 같습니다.

사양을 실행 가능한 계약으로 사용합니다.

OpenAPI 자체가 익숙하지 않다면 OpenAPI Specification 튜토리얼부터 시작하는 것이 좋습니다.

Specmatic은 Pact와 동일한가요?

아닙니다.

Pact는 소비자 주도 계약 테스트에 가깝습니다. 소비자가 기대치를 브로커에 게시하고, 공급자가 그 기대치를 검증합니다.

Specmatic은 계약 주도 방식입니다. OpenAPI 같은 공유 사양이 단일 계약이며, Specmatic은 이 계약으로 공급자를 검증하고 소비자에게 스텁을 제공합니다.

둘 다 통합 문제를 줄이는 데 도움이 되지만 계약을 구성하는 방식이 다릅니다.

Specmatic이 OpenAPI 사양을 생성할 수 있나요?

네. Specmatic은 기존 서비스 앞에서 프록시로 실행되어 실제 요청과 응답을 캡처할 수 있습니다. 이 트래픽을 기반으로 OpenAPI 문서와 예제 파일을 생성할 수 있습니다.

이미 작동하는 API는 있지만 공식 사양이 없을 때 유용합니다.

결론

Specmatic은 실행 중인 서비스가 OpenAPI 사양과 계속 일치하도록 만드는 도구입니다. 사양을 실행 가능하게 만들어 계약 테스트와 스텁 서버를 같은 파일에서 제공합니다. 하위 호환성 검사까지 추가하면 마이크로서비스 환경에서 API 변경 리스크를 줄일 수 있습니다.

터미널과 CI 중심으로 작업하고, OpenAPI 사양을 진실의 원천으로 관리한다면 Specmatic은 적합한 선택입니다.

동일한 OpenAPI 파일을 기반으로 설계, 테스트, 목킹, 문서를 하나의 시각적 워크스페이스에서 관리하고 싶다면 Apidog를 사용해보세요. Apidog는 스키마에 대해 응답을 검증하고, 코드 없이 엔드포인트를 목킹하며, 사양을 실행 가능한 테스트 컬렉션으로 변환합니다. Apidog를 다운로드하여 설계부터 테스트까지 한 흐름에서 확인할 수 있습니다.

Top comments (0)