Dredd 없이 API 명세 기반 API 검증 방법

Dredd는 실제 문제를 깔끔하게 해결합니다. API 설명(OpenAPI 문서 또는 API Blueprint 파일)과 실행 중인 서버를 지정하면, 설명에 있는 모든 예시를 읽고, 라이브 백엔드에 일치하는 요청을 보내 실제 응답이 사양이 약속한 것과 일치하는지 확인합니다. 사양에 GET /orders/{id}가 id 및 status 필드와 함께 200을 반환한다고 되어 있다면, Dredd는 실행 중인 서비스가 실제로 그렇게 하는지 확인합니다. 사양은 조용히 부패하는 문서가 아니라, 문제가 발생하면 크게 실패를 알리는 테스트가 됩니다.

API 설명에 대해 구현을 검증하는 이 아이디어는 올바른 접근 방식입니다. 사양이 명시하는 내용과 서비스가 실제로 수행하는 내용 간의 불일치는 API 작업에서 가장 비용이 많이 드는 조용한 버그 중 하나입니다. 프론트엔드 팀이 문서화된 계약에 따라 코드를 작성했는데, 백엔드가 필드 이름을 변경하고 아무도 문서를 업데이트하지 않아 프로덕션에서 문제가 발생합니다. Dredd는 바로 이러한 유형의 오류를 잡아내며, 수년간 명령줄에서 이 작업을 수행하는 데 가장 많이 사용되는 오픈 소스 도구였습니다.

마찰은 개념 자체가 아니라 설정과 유지보수에 있습니다. Dredd는 자체 구성 파일, 사소한 경우를 넘어선 상황을 위한 원하는 언어의 훅 파일, 그리고 다른 모든 것과 함께 수동으로 유지 관리해야 하는 별도의 사양 아티팩트가 필요한 Node.js CLI입니다. Dredd가 제공하는 것과 동일한 결과, 즉 구현이 OpenAPI 계약과 더 이상 일치하지 않을 때 실패하는 CI 게이트를 원하지만, 훅 도구 체인을 구축하거나 사양을 세 번째로 분리된 파일로 유지하고 싶지 않다면, Apidog가 이러한 워크플로우를 위해 만들어졌습니다. Apidog는 사양, 테스트 및 유효성 검사를 하나의 프로젝트에 통합하고, npm CLI에서 전체를 헤드리스로 실행합니다. 이 가이드는 Dredd가 잘하는 점에 대해 공정하며, 통합된 경로가 어디에서 이점을 가지는지 명확하게 설명합니다.

Dredd의 장점

Dredd는 그 명성을 얻을 자격이 있으므로, 먼저 Dredd의 장점을 살펴보겠습니다.

구현을 테스트합니다. 목업이 아닙니다. 이것이 핵심입니다. 많은 도구들이 OpenAPI 파일이 잘 구성되었는지 또는 목업 서버가 제대로 작동하는지 검증합니다. Dredd는 더 어려운 작업을 수행합니다. 실제 실행 중인 백엔드를 호출하고, 문서화된 예시에 대해 반환되는 실제 바이트를 확인합니다. Dredd 테스트 통과는 이론이 아닌, 배포된 서비스와 사양이 현재 일치한다는 것을 의미합니다.

API Blueprint와 OpenAPI 모두를 지원합니다. Dredd는 마크다운 기반 설명 형식인 API Blueprint와 함께 성장했으며, 나중에 OpenAPI 2 및 3 지원을 추가했습니다. 레거시 Blueprint 파일이나 Swagger 문서가 있는 경우, Dredd는 변환 단계 없이 이를 읽을 수 있습니다.

언어에 구애받지 않는 훅. 기본 요청 및 비교 루프만으로는 충분하지 않을 때, 즉 인증 토큰이 필요하거나, 테스트 전에 데이터베이스를 시드해야 하거나, 트랜잭션을 건너뛰어야 할 때 Dredd는 훅을 작성할 수 있도록 합니다. 훅 핸들러는 기본적으로 Node에서 실행되지만, Dredd는 Python, Ruby, Go, PHP, Rust 등 다양한 언어의 훅에 대한 프로토콜 지원을 제공합니다. 팀은 이미 익숙한 언어로 설정 로직을 작성할 수 있습니다.

오픈 소스이며 CI 친화적입니다. Dredd는 npm install -g dredd로 설치되며, 단일 명령으로 실행되고, 유효성 검사에 실패하면 0이 아닌 값으로 종료되므로, 어떤 CI 시스템이든 이를 통해 빌드를 제어할 수 있습니다. SaaS 계정, 좌석별 가격 책정, 가입할 것이 아무것도 없습니다. 자체 호스팅되는 스크립트 가능한 계약 검사를 원하는 팀에게는 중요합니다.

이 모든 것이 불필요한 내용이 아닙니다. Dredd는 명확한 임무를 가진 견고한 도구입니다. 문제는 세 가지 개별 아티팩트와 훅 파일이라는 Dredd의 모델이 실제로 작업하고 싶은 방식과 일치하는지 여부입니다.

마찰이 발생하는 지점

Dredd 모델에는 세 가지 비용이 따르며, 그 비용이 얼마나 큰지는 설정에 따라 달라집니다.

사양은 수동으로 유지 관리하는 세 번째 아티팩트입니다. Dredd는 설명 파일에 대해 구현을 검증하는데, 이는 정확하지만, 해당 설명은 일반적으로 API를 설계하고 테스트하는 곳과 분리되어 있습니다. openapi.yaml을 수동으로 편집하고, 테스트 시나리오는 다른 곳에 보관하며, 실행 중인 서비스는 또 다른 곳에 유지합니다. Dredd는 이 세 가지 중 두 가지를 서로 비교하여 확인합니다. 사양 자체를 정확하게 유지하는 것은 여전히 수동 작업이며, 현실과 조용히 멀어진 사양은 결과적으로 성공(초록색)으로 보이지만 실제로는 잘못된 Dredd 실행을 초래합니다.

훅은 작성하고 유지 관리해야 하는 코드입니다. API에 인증, 순서 지정 또는 테스트 데이터가 필요한 순간, 예시 기반 루프만으로는 충분하지 않게 됩니다. hooks.js(또는 Python, Ruby 등 해당 언어의 파일)를 작성하고 dredd.yml을 통해 연결하며, 이제 첫 번째 코드를 테스트 가능하게 만드는 것이 유일한 목적인 두 번째 코드베이스를 소유하게 됩니다. 간단한 읽기 전용 API의 경우 Dredd는 거의 구성이 필요 없습니다. 로그인 및 상태 저장 엔드포인트가 있는 실제 API의 경우 훅 파일이 커지고, 이는 다른 이름의 접착 코드(glue code)가 됩니다.

예시 기반 커버리지에는 공백이 있습니다. Dredd는 설명에 있는 예시를 테스트합니다. 엔드포인트에 문서화된 예시 응답이 하나뿐이라면, 그것만 확인됩니다. 사양에 예시로 명시되지 않은 엣지 케이스, 오류 경로 및 유효성 검사 규칙은 사양을 확장하거나 더 많은 훅을 작성하여 추가하지 않으면 테스트되지 않습니다. 커버리지는 유지 관리하는 예시만큼만 좋으며, 그 이상은 아닙니다.

통합된 경로: 하나의 프로젝트에서 사양 및 테스트 관리

Apidog가 추구하는 다른 방식은 다음과 같습니다. API 정의는 수동으로 동기화하는 세 번째 파일이 아닙니다. API를 실행하는 테스트 및 빌드를 제어하는 유효성 검사와 동일한 프로젝트 내에 존재하는 진실의 원천입니다. 스키마를 변경하면 테스트는 새로운 형태를 인식합니다. 리포지토리 한 구석에서 따로 떠다니는 별도의 openapi.yaml 파일도 없고, 사양과 실제 작동하는 테스트 사이에 존재하는 훅 파일도 없습니다.

API를 한 번만 설계하거나 가져옵니다. Apidog는 OpenAPI 2 및 3을 읽고, Swagger 문서를 가져오며, 클릭 한 번으로 Postman 컬렉션을 가져옵니다. 엔드포인트, 요청 스키마, 응답 스키마 및 예시 응답은 모두 하나의 프로젝트에 통합됩니다. 이미 스펙 우선(spec-first)으로 생각하고 있다면, 이는 Dredd가 권장하는 것과 동일한 원칙이지만, 사양이 분리된 파일로 존재하지 않는다는 차이가 있습니다. 이 워크플로우의 심층적인 내용은 스펙 우선 API 개발에 있으며, 테스트 실행 전에 사양 문서 자체를 검증하고 싶다면 OpenAPI 사양 검증에서 해당 단계를 다룹니다.

이러한 실제 스키마에 대해 유효성 검사를 구축합니다. 테스트 시나리오가 GET /orders/{id}를 호출할 때, 응답을 수동으로 복사한 예시가 아닌 Apidog가 해당 엔드포인트에 대해 이미 가지고 있는 스키마와 비교하여 단언합니다. 이는 Dredd가 수행하는 사양 대 구현 확인과 동일하지만, 한 가지 차이점이 있습니다. 확인되는 사양은 API를 설계할 때 사용한 스키마와 동일하므로 테스트 스위트와 조용히 불일치할 수 없습니다. 이는 세 번째 아티팩트 없이 수행되는 계약 테스트이며, 이 원칙에 대한 더 넓은 그림을 원한다면 API 계약 테스트와 양방향 계약 테스트를 통해 더 깊이 탐구할 수 있습니다.

Dredd가 훅 파일, 인증 토큰, 순서 지정, 시딩으로 처리하는 설정은 대부분의 웹 개발자가 이미 작성하는 JavaScript의 사전 및 사후 요청 스크립트로 처리할 수 있습니다. 구성 파일을 통해 연결된 별도의 훅 코드베이스가 없습니다. 로직은 지원하는 테스트 바로 옆에 있습니다.

Apidog CLI 설치 및 실행

러너는 npm에 apidog-cli로 게시되어 있습니다. Node.js가 있다면 필요한 모든 것을 갖춘 것입니다:

npm install -g apidog-cli

바이너리는 apidog이므로, 모든 실행은 apidog run으로 시작합니다. 테스트 시나리오를 실행하려면 액세스 토큰, 시나리오 ID 및 환경 ID를 전달합니다:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

이 ID들을 수동으로 입력할 필요가 없습니다. Apidog에서 테스트 시나리오를 열고, CI/CD 탭으로 이동하여 명령줄 옵션을 선택한 다음 액세스 토큰을 생성하십시오. Apidog는 시나리오 및 환경 ID가 이미 채워진 완전한 apidog run 명령을 자동으로 생성합니다. 한 번 복사한 다음 거기에서 토큰을 매개변수화하십시오. 액세스 토큰을 비밀번호처럼 다루십시오. 여기 모든 예시에서처럼 CI 시스템에 비밀로 저장하고 $APIDOG_ACCESS_TOKEN으로 참조하십시오.

하나 이상의 시나리오를 실행하려면 단일 ID 대신 폴더 또는 테스트 스위트를 러너에 지정하고 리포터를 선택하십시오:

apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -e 1629989 -r html,junit --out-dir ./test-reports

-r 플래그는 리포터를 선택합니다. Apidog는 읽기 쉬운 터미널 출력을 위한 cli, 빌드 아티팩트로 보관할 수 있는 독립형 보고서를 위한 html, 거의 모든 CI 대시보드가 통과/실패 트리로 구문 분석하는 XML을 위한 junit, 그리고 원시 구조화된 결과를 위한 json을 지원합니다. 러너에 대해 더 자세히 알아보려면 apidog run --help를 실행하여 전체 플래그 목록을 확인하십시오.

비교

이 표를 솔직하게 읽어보십시오. 완전한 자체 호스팅, 오픈 소스, 계정이 필요 없는 도구를 원하고 팀이 훅 파일 유지 관리에 익숙하다면, Dredd의 모델은 깔끔하게 들어맞으며 단순히 전환하는 것만으로는 아무것도 얻지 못할 것입니다. 통합된 경로를 선택하는 경우는 특정합니다. 사양이 계속해서 멀어지는 세 번째 파일이라는 점에 지쳤거나, 훅 코드베이스를 소유하고 싶지 않거나, 동일한 프로젝트에서 설계, 테스트 및 계약 검사를 함께 처리하고 싶을 때입니다.

CI에 통합하기

Apidog CLI는 통과 시 0을, 실패 시 0이 아닌 값을 반환하므로 Dredd와 마찬가지로 모든 CI 시스템이 이를 기반으로 빌드를 제어할 수 있습니다. 최소한의 GitHub Actions 작업에는 Node와 하나의 실행 단계가 필요합니다:

name: api-contract-check
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - run: apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

이것이 전체 파이프라인입니다. Dredd 작업도 유사하게 CLI를 설치하고 명령 하나를 실행하지만, 사양 파일과 훅 파일을 지정하고 둘 다 최신 상태로 유지해야 합니다. 유효성 검사는 동일한 방식으로 실행되지만, 차이점은 거기에 도달하기 위해 유지 관리해야 하는 아티팩트의 수입니다.

Dredd를 사용하려는 이유가 사양과 서비스가 서로 정직하게 일치하도록 하는 것이었다면, 동일한 논리가 다른 도구에서도 나타납니다. 팀들은 Swagger와 Postman이 서로 멀어지는 문제에 부딪히는데, 이는 Swagger와 Postman 불일치에 대한 OpenAPI 기반 테스트에서 다루고 있으며, Java 개발자들은 Rest Assured에서 이 문제에 직면합니다. 대안 이야기는 강력한 도구이지만 원치 않는 계층을 추가하는 모델이라는 점에서 비슷합니다. IDE를 떠나고 싶지 않다면 VS Code 확장을 사용하여 편집기에서 Apidog를 구동할 수도 있습니다.

자주 묻는 질문 (FAQ)

Apidog가 Dredd 설정을 완벽하게 대체할 수 있나요? 아니요, 그리고 그렇게 주장하지도 않습니다. dredd.yml과 hooks.js를 읽어 Apidog 시나리오를 생성하는 변환기는 없습니다. OpenAPI 사양을 가져와 비주얼 편집기에서 유효성 검사를 다시 구축합니다. 장점은 훅 파일과 분리된 사양을 유지 관리하지 않아도 된다는 것이고, 비용은 한 번의 재구축입니다. 작동하는 크고 성숙한 Dredd 스위트가 있다면, 그 재구축은 공짜가 아닌 실제 결정입니다.

Apidog도 Dredd처럼 라이브 구현을 검증하나요? 네. CLI는 실행 중인 서비스에 실제 요청을 보내고, 프로젝트 내 스키마에 대해 실제 응답을 단언합니다. 이는 Dredd가 수행하는 것과 동일한 사양 대 구현 확인입니다. 차이점은 확인되는 스키마가 API를 설계할 때 사용한 스키마와 동일하므로 테스트에서 벗어나지 않는다는 것입니다.

Dredd 훅처럼 인증 및 테스트 설정을 처리할 수 있나요? 네. Apidog는 JavaScript의 사전 요청 및 사후 요청 스크립트를 지원하므로, 코드를 통해 인증 토큰을 가져오고, 데이터를 시드하고, 페이로드를 변환하거나, 동적 단언을 구축할 수 있습니다. 로직은 구성 파일을 통해 연결된 별도의 훅 파일이 아니라, 지원하는 시나리오 내에 존재합니다.

Dredd가 Apidog가 하지 못하는 일을 하나요? 몇 가지 있습니다. Dredd는 계정 없이 완전 자체 호스팅되고 오픈 소스이며, 오래된 마크다운 설명 형식인 API Blueprint를 기본적으로 읽습니다. 계정이 필요 없는 완전 로컬 도구 또는 레거시 Blueprint 파일이 설정의 핵심이라면, 전환하기 전에 신중하게 고려하십시오.

Apidog는 어떤 형식을 읽나요? OpenAPI 2 및 3, Swagger 문서, 그리고 Postman 컬렉션을 모두 하나의 프로젝트로 가져올 수 있습니다. 먼저 형식 차이를 이해하고 싶다면 Swagger 대 OpenAPI 및 OpenAPI 사양 개요에서 모두 설명하고 있습니다.

결론

Dredd는 핵심 아이디어를 제대로 파악했습니다. API 설명은 실행 중인 서비스를 테스트하는 데 사용되어야 하며, 불일치가 발생하는 문서가 되어서는 안 됩니다. 자체 호스팅되는 오픈 소스 CLI를 원하고 사양 파일과 훅 파일을 유지 관리하는 데 만족한다면, Dredd는 현명한 선택이며 계속 사용해야 합니다.

통합된 경로는 그러한 유지 관리 부분을 없애고 싶을 때를 위한 것입니다. Apidog는 사양, 테스트 및 유효성 검사를 하나의 프로젝트에 통합하여, 확인하는 계약이 설계한 것과 동일하게 유지되며, 소유할 훅 코드베이스 없이 apidog run 명령으로 모든 것을 실행합니다. Apidog를 다운로드하고 기존 OpenAPI 파일을 가져와 단일 명령으로 사양 대 구현 확인을 실행하는 것을 확인하십시오.