Apidog — API 설계·테스트·문서화·Mock 서버를 하나로

개념

도구 하나가 아니라 흐름 전체를 덮는다

지금까지 배운 API 도구들은 대부분 이미 만들어진 API를 두드려보는 도구였다. 모듈 12(레슨 2)의 Postman도, 이 모듈 레슨 1·2의 Insomnia·Hoppscotch도 마찬가지다. 개발자가 API를 완성해서 URL을 알려줘야 비로소 QA의 작업이 시작된다.

Apidog은 시작점이 다르다. API를 설계하는 화면에서 출발 한다. 엔드포인트, 요청·응답 필드, 타입, 필수 여부를 먼저 정의하면 그 정의(스펙)를 뿌리 삼아 네 가지가 한꺼번에 따라온다.

API 스펙(설계)  ──┬──▶  문서       (자동 생성, 항상 스펙과 동일)
                  ├──▶  Mock 서버  (스펙대로 가짜 응답을 즉시 제공)
                  ├──▶  테스트 케이스 (스펙 기반 어서션 뼈대 자동 생성)
                  └──▶  실제 API 호출 (Postman처럼 요청·응답 확인)

핵심은 화살표의 방향이다. 네 가지가 각각 따로 관리되는 게 아니라 하나의 스펙에서 파생 되므로, 스펙을 고치면 나머지가 함께 따라 움직인다.

모듈 12에서 배운 계약 테스트가 화면 안으로 들어온 것

모듈 12(레슨 4)에서 OpenAPI 스펙과 실제 응답이 일치하는지 검증하는 계약 테스트 를 배웠다. 그때는 스펙 파일(YAML)을 따로 관리하고, 검증 코드를 따로 짜고, 실행도 따로 했다.

Apidog에서는 이 셋이 같은 화면에 있다. 설계 탭에서 정의한 스키마가 곧 계약이고, "요청 보내기" 버튼을 누르면 실제 응답이 그 계약을 지켰는지 를 자동으로 대조해 보여준다. totalPrice를 숫자로 정의했는데 문자열 "9000" 이 오면, 요청 결과 화면에서 바로 불일치가 표시되는 식이다 — 모듈 12(레슨 4) 과제 1에서 눈으로 찾아냈던 그 위반을 도구가 대신 짚어준다.

Mock 서버 — API가 없어도 테스트를 시작한다

Apidog에서 가장 QA에게 의미 있는 기능은 Mock 서버 다. 스펙만 정의해두면, 백엔드 구현이 한 줄도 없어도 그 스펙대로 그럴듯한 응답을 돌려주는 임시 서버 주소가 생긴다.

설계만 끝난 상태
  프런트엔드 → Mock 서버 → 스펙대로 생긴 가짜 응답 → 화면 개발 진행
  QA        → Mock 서버 → 응답 구조 확인 → 테스트 케이스 미리 설계

이건 모듈 1(레슨 1)에서 배운 "결함은 일찍 찾을수록 싸다" 를 도구로 구현한 것이다. 필수 필드가 빠졌다거나, 에러 응답 형식이 정해지지 않았다거나, 페이지네이션 규칙이 모호하다는 문제를 코드가 써지기 전에 발견하면 수정 비용은 스펙 한 줄을 고치는 정도다. 같은 문제를 통합 테스트 단계에서 발견하면 양쪽 팀의 코드를 모두 고쳐야 한다.

왜 통합형 도구가 뜨는가

예전에는 이 흐름이 도구마다 쪼개져 있었다.

네 곳에 같은 정보를 손으로 네 번 적으니 어긋나는 게 정상이다. 모듈 2에서 배운 "요구사항 문서와 실제 구현이 달라서 생기는 결함"과 구조가 완전히 같다 — 진실의 출처(single source of truth)가 여러 개면 반드시 갈라진다. Apidog 같은 통합 플랫폼은 출처를 스펙 하나로 못 박아서 이 갈라짐 자체를 없애려는 시도다.

그래도 만능은 아니다

통합의 대가로 팀 전체가 같은 도구를 써야 효과가 난다. 개발자는 코드에서 스펙을 뽑고 QA만 Apidog을 쓰면, 스펙이 또 두 벌이 되어 문제가 그대로 재현된다. 도구가 아니라 "스펙을 하나로 유지한다"는 합의가 본질이다.

실무에서 왜 필요한가

스프린트 초반, 백엔드가 아직 개발 중일 때 QA가 할 수 있는 일이 "기다리기"밖에 없는 팀이 많다. Apidog의 설계·Mock 흐름을 쓰면 이 기간에 QA가 스펙 리뷰(필수 필드 누락, 에러 코드 미정의, 경계값 규칙 부재)를 하고 Mock 응답으로 테스트 케이스를 미리 짜둘 수 있다 — 모듈 2(레슨 6)에서 배운 "요구사항 단계에서 질문하는 QA"를 API 레벨에서 실천하는 가장 구체적인 방법이다. 또 팀이 이미 Postman을 쓰고 있어도 컬렉션·OpenAPI 파일을 가져올 수 있어, 도구를 갈아엎지 않고 설계·Mock 부분만 얹는 점진적 도입이 가능하다.

실습 과제

과제 1 — 스펙 먼저 설계하기 (10분)

"쿠폰 조회 API"(GET /coupons/{code})의 스펙을 표로 설계한다. 응답 필드 4개 이상을 정하고 각각 타입·필수 여부를 적는다. 실패 응답(존재 하지 않는 쿠폰, 만료된 쿠폰)의 상태 코드와 본문 형식도 함께 정한다.

과제 2 — Mock 서버로 앞당길 수 있는 일 찾기 (10분)

내가 맡은(또는 상상한) 기능에서, 백엔드 완성을 기다리는 동안 Mock 서버만으로 미리 할 수 있는 QA 작업을 3가지 적는다. 각각에 대해 "Mock으로는 검증할 수 없고 실제 API가 있어야만 확인 가능한 것"도 하나씩 짝지어 적는다.

과제 3 — 도구 갈라짐 진단하기 (5분)

모듈 12(레슨 4)의 계약 테스트를 떠올리며, 지금 스펙·테스트·문서가 따로 관리되는 팀에서 문서와 실제 API가 벌어졌다는 것을 가장 먼저 알아채는 사람 은 보통 누구일지, 그리고 왜 그 시점이 이미 늦은 것인지 3줄로 적는다.

자가 체크리스트

• Apidog이 Postman·Insomnia와 출발점에서 어떻게 다른지 설명할 수 있다
• 하나의 스펙에서 문서·Mock·테스트가 파생되는 구조를 그림으로 그릴 수 있다
• 모듈 12에서 배운 계약 테스트가 Apidog에서 어떤 형태로 나타나는지 설명할 수 있다
• Mock 서버가 "결함은 일찍 찾을수록 싸다"와 어떻게 연결되는지 설명할 수 있다
• 통합 도구가 효과를 내려면 팀 전체의 합의가 필요한 이유를 말할 수 있다

흔한 실수

• Apidog을 그냥 "Postman 대체제"로만 쓴다. 요청 보내기 기능만 쓰면 도구를 바꾼 의미가 거의 없다 — 설계·Mock 단계에 QA가 참여할 때 비로소 차별점이 생긴다.
• Mock 응답이 통과했다고 API가 검증됐다고 착각한다. Mock은 스펙대로 생긴 가짜일 뿐이라 실제 비즈니스 로직(할인 계산, 재고 차감, 권한 검사)은 전혀 검증하지 못한다.
• 스펙을 도구 안에만 두고 팀과 공유하지 않는다. 개발자가 별도 스펙을 유지하면 진실의 출처가 다시 둘로 갈라져, 통합 도구를 쓰는 이유 자체가 사라진다.
• 설계 단계 리뷰에서 성공 응답만 정하고 에러 응답을 미룬다. 실무 결함의 상당수는 에러 경로에서 나온다 — 스펙 리뷰에서 QA가 꼭 짚어야 할 지점이다.

참고 자료

• Apidog 공식 문서 — 설계·Mock·테스트 기능의 공식 가이드
• Apidog — Mock 서버 가이드 — 스펙 기반 Mock 응답 생성 방법
• OpenAPI Specification — Apidog이 가져오기·내보내기로 다루는 표준 스펙 형식