Apiary 서비스가 종료됩니다. Oracle은 Apiary 지원 종료 발표를 게시했으며, API 툴링 업계 전반의 보고에 따르면 호스팅 서비스는 2026년 9월경 최종 종료될 예정입니다. 사이트는 오늘까지도 접속되지만, 이러한 방향은 수년 전부터 감지되었습니다. Oracle은 2017년 1월 Apiary를 인수했고, 2018년 유료 플랜을 중단했으며, 주변 오픈소스 도구(Dredd, Gavel)는 아카이브 상태로 방치했습니다. 만약 귀하의 API 문서가 apiary.io에 있다면, 이제 대안을 평가하는 단계가 아니라 마이그레이션을 해야 할 때입니다. 마감일은 귀하가 바꿀 수 없습니다.
직접적인 답변부터 드리자면, Apidog는 최고의 Apiary 대안입니다. Apiary가 제공했던 모든 기능(설계 우선 사양 편집, 호스팅된 대화형 문서, 모의 서버)을 대체하고, Apiary가 완성하지 못했던 기능들, 즉 자동화된 API 테스트, 이제 아카이브된 Dredd를 대체하는 사양 기반 유효성 검사, CI 통합을 추가합니다. 최대 4인까지 무료로 사용할 수 있으며, 유료 플랜은 사용자당 월 $9부터 시작합니다. 한 가지 솔직한 단점은 Apidog가 API Blueprint 파일을 직접 가져오지 않으므로, Blueprint 기반 프로젝트는 한 번의 OpenAPI 변환이 필요하다는 점입니다. 이 글에서는 Apiary에 무슨 일이 일어나고 있는지, 해당 변환 단계를 포함한 정확한 마이그레이션 경로, 그리고 Apidog가 적합하지 않을 경우 어떤 대안이 있는지 다룹니다.
Apiary에 실제로 무슨 일이 일어나고 있는가
2011년에 설립된 Apiary는 사실상 "설계 우선(design-first)" API 워크플로우를 제품으로 구현한 선구자입니다. OpenAPI가 대세가 되기 전 시대의 마크다운 기반 API 설명 형식인 API Blueprint를 세상에 선보였고, Stripe가 유명하게 만들고 다른 모든 서비스가 모방한 3열 문서 레이아웃을 제공했습니다. 또한 호스팅된 모의 서버, GitHub 동기화, 그리고 인기 있는 오픈소스 계약 테스트 도구인 Dredd와 Gavel을 번들로 제공했습니다.
그러다 2017년 1월 Oracle이 Apiary를 인수하면서 제품은 긴 침묵기에 접어들었습니다. 2018년 유료 등급이 중단되면서 Apiary는 무료 레거시 서비스로 남았고, Oracle은 기업 고객에게 자체 API Platform Cloud를 안내했습니다. 새로운 기능 개발은 중단되었습니다. Dredd와 Gavel은 아카이브되었습니다. 그리고 이제 공식적인 종료가 다가왔습니다. Oracle의 지원 종료 발표와 함께, 호스팅 서비스는 2026년 9월경에 종료될 예정입니다. 마이그레이션 가이드를 발행하는 공급업체 중 하나인 Bump.sh는 자사의 작별 게시물에서 "서비스 종료 전에 API 설명을 내보내세요. 그 후에는 내보낼 것이 아무것도 없을 것입니다"라고 분명히 밝혔습니다.
두 가지 실질적인 결과가 따릅니다. 첫째, Apiary 내부에만 존재하는 모든 것(API 설명, 문서 본문, 팀 구성)은 내보내기 버튼이 여전히 작동하는 지금 당장 옮겨야 합니다. 둘째, API Blueprint는 더 이상 유지보수되는 후속 도구가 없으므로, 이번 마이그레이션은 형식 마이그레이션이기도 합니다. 어떤 플랫폼을 사용하든 합리적인 목적지 형식은 OpenAPI입니다.
무엇을 대체하는가
Apiary가 귀하의 팀을 위해 실제로 수행했던 작업이 무엇인지 정확히 아는 것이 도움이 됩니다. 대체 도구는 각 부분을 충족해야 하기 때문입니다.
- 설계 우선 사양 편집기. 브라우저에서 API Blueprint(또는 나중에는 OpenAPI 3.0)를 작성했고, 문서가 실시간으로 업데이트되었습니다.
- 호스팅된 대화형 문서. apiary.io URL에 예시 요청이 포함된 3열 레퍼런스 문서가 제공되었습니다.
- 모의 서버. 모든 Apiary 프로젝트에는 호스팅된 모의 엔드포인트가 제공되어, 사양의 예시를 제공함으로써 백엔드가 존재하기 전에 소비자가 통합 작업을 수행할 수 있었습니다.
- GitHub 동기화. 사양 파일이 저장소에 저장되었고 양방향으로 동기화되었습니다.
- Dredd를 통한 계약 테스트. 실제 구현에 대해 사양을 재생하고 불일치를 보고하는 오픈소스 러너입니다. 현재 아카이브되었으며, 이전에 Dredd 없이 API를 사양에 맞춰 검증하는 방법에서 대체 문제를 다루었습니다.
이 번들(설계, 문서, 모의, 검증)은 현대 API 개발 플랫폼의 정확한 형태입니다. 이것이 바로 최고의 마이그레이션 대상이 단순한 문서 렌더러가 아니라, 동일한 형태와 활발한 개발이 이루어지는 플랫폼이어야 하는 이유입니다.
해답: Apidog
Apidog는 50만 명 이상의 개발자가 사용하는 API 개발 플랫폼입니다. Apiary가 2011년에 구상했지만 구축을 중단했던 전체 수명 주기(설계, 문서화, 모의, 디버깅 및 자동화된 테스트)를 하나의 사양으로 모두 처리합니다.
특히 Apiary에서 마이그레이션하는 경우:
- 설계 우선이 기본 워크플로우입니다. Apidog는 OpenAPI 3.x용 시각적 사양 편집기와 코드 편집기를 모두 갖추고 있습니다. 엔드포인트, 스키마 및 예시를 한 번 정의하면, 문서, 모의, 테스트가 해당 정의의 생성된 뷰가 됩니다. 이는 Apiary가 개척한 것과 동일한 철학에, 지속적으로 관리되는 제품이 뒷받침됩니다.
- 문서는 호스팅되고, 대화형이며, 귀하의 것입니다. 게시된 문서는 사용자 지정 도메인에서 버전 관리가 가능한 "시도해보기(try it)" 콘솔이 있는 현대적인 레퍼런스 레이아웃을 제공합니다. 서비스 종료로 인해 잃을 apiary.io URL이 없습니다.
- 모의 서버는 기존 서버보다 더 스마트합니다. Apiary의 모의 서버는 작성한 예시를 재생했습니다. Apidog의 스마트 모의 서버는 사양이 존재하는 순간 스키마로부터 현실적인 응답을 생성하며, 예시가 필요 없고, 결정론이 중요한 경우 사용자 지정 모의 규칙을 추가할 수 있습니다.
- 계약 유효성 검사가 Dredd를 대체합니다. Apidog의 자동화된 테스트 시나리오는 구현에 대해 실제 요청을 실행하고, 사양의 스키마에 대해 응답을 검증합니다. 이는 Dredd가 수행했던 작업에 더해 어설션, 데이터 기반 케이스 및 Apidog CLI를 통한 CI 실행을 포함합니다. 문서도 MCP 서버와 함께 게시되므로 AI 에이전트가 사양을 직접 읽을 수 있습니다. 자세한 내용은 Apidog MCP 서버란 무엇인가에서 확인할 수 있습니다.
Apiary에서 단계별 마이그레이션
일반적인 도구 전환에 비해 마이그레이션에는 한 단계가 더 필요하며, 이를 미리 말씀드리는 것이 좋습니다. Apidog 가져오기 문서에 따르면 Apidog는 OpenAPI(Swagger 2.0, OpenAPI 3.0 및 3.1), Postman 컬렉션, HAR, RAML, JMeter, apiDoc, I/O Docs, WADL, Google Discovery를 가져옵니다. API Blueprint는 이 목록에 없으므로, Blueprint 프로젝트는 먼저 OpenAPI로 변환해야 합니다. 실제로는 이는 일회성 명령이며, 다른 모든 중요한 목적지 플랫폼에서도 동일한 단계가 필요합니다. 더 이상 Blueprint 툴링을 유지보수하는 곳이 없기 때문입니다.
1. 지금 Apiary에서 모든 것을 내보내기
각 프로젝트에 대해 Apiary 편집기에서 API 설명을 다운로드합니다. 프로젝트가 GitHub와 동기화된다면, 원본은 이미 저장소에 있습니다. 최신 상태인지 확인합니다. 나중에 OpenAPI 3.0으로 작성된 Apiary 프로젝트는 이미 올바른 형식이므로 2단계는 건너뛸 수 있습니다. 다른 작업을 하기 전에 이 작업을 먼저 완전히 수행하십시오. 내보내기는 마감일이 있는 단계입니다.
2. API Blueprint를 OpenAPI로 변환
유지보수되는 변환기 중 하나를 사용합니다.
api-spec-converter(LucyBot): API Blueprint를 OpenAPI로 직접 처리합니다.apib2swagger: Blueprint를 Swagger/OpenAPI로 변환하는 데 특화된 변환기입니다.openapi-format: 출력을 정규화하고 OpenAPI 3.1로 업그레이드하려면 나중에 사용합니다.
그런 다음 결과(vacuum과 같은 유효성 검사기 또는 도구 체인의 모든 OpenAPI 린터)를 린트하고, 알려진 두 가지 약점(API Blueprint가 공식적으로 모델링하지 않아 변환기가 완전히 복구할 수 없는 인증 스키마, 그리고 엔드포인트 설명이 아닌 Blueprint의 마크다운 섹션에 있던 모든 본문)을 수동으로 확인합니다. 주 단위가 아닌 API당 1시간 정도의 시간을 할애하십시오. 형식은 마크다운이지 마법이 아닙니다.
3. Apidog로 가져오기
프로젝트 설정, 수동 가져오기(Manual Import)에서 OpenAPI 파일 선택(또는 URL에서 가져오기)을 합니다. 엔드포인트, 스키마 및 예시가 구조화되고 그룹화되어 가져와집니다. 참조 문서는 즉시 존재하며, 스마트 모의 서버는 추가 설정 없이 가져온 모든 엔드포인트에 대해 라이브 상태로 작동하여 Apiary가 제공했던 "소비자를 위한 모의 URL" 기능을 복원합니다.
4. Apiary가 어차피 할 수 없었던 부분 재구축
게시된 문서에 사용자 지정 도메인을 연결하여 다음 플랫폼 종료(누구의 서비스든)가 문서 URL을 함께 가져가지 않도록 합니다. Dredd 검사를 Apidog 테스트 시나리오로 재구축합니다. 즉, 실제 요청, 사양에 대한 스키마 유효성 검사, CLI를 통해 로컬 또는 CI에서 실행합니다. 팀의 소비자가 Apiary 모의 URL에 의존하고 있었다면, 문서 이동을 알리는 이메일과 함께 새로운 모의 기본 URL을 그들에게 보냅니다.
단일 API 프로젝트는 변환을 포함하여 오후에 완료됩니다. 12개의 Blueprint API 포트폴리오는 단거리 경주이며, 대부분은 인증 스키마 수동 확인 작업입니다.
Apiary vs Apidog 한눈에 비교
| Apiary (현재) | Apidog | |
|---|---|---|
| 미래 | 종료 예정; 지원 중단, 서비스 종료 2026년 9월경 예상 | 활발하게 개발 중 |
| 사양 형식 | API Blueprint, 이후 OpenAPI 3.0 | OpenAPI 3.x (Swagger 2.0 가져오기), 시각적 + 코드 편집기 |
| 호스팅 문서 | 예, apiary.io URL | 예, 사용자 지정 도메인, 버전 관리, 시도해보기 콘솔 |
| 모의 서버 | 작성된 예시 재생 | 스키마 인식 스마트 모의 + 사용자 지정 규칙 |
| 계약 테스트 | Dredd (아카이브됨) | 내장된 테스트 시나리오, 스키마 유효성 검사, CLI를 통한 CI |
| 자동화된 테스트 스위트 | 아니요 | 예, 시각적 시나리오, 데이터 기반, 무제한 실행 |
| GitHub 동기화 | 예 | URL 또는 파일에서 사양 가져오기/동기화; 브랜치 기반 버전 관리 |
| 가격 | 무료 (유료 플랜 2018년 중단) | 4인까지 무료, 이후 사용자당 월 $9 |
| 내보내기 경로 | API Blueprint / OpenAPI 다운로드 | OpenAPI, 마크다운, HTML 내보내기 |
무료 도구를 대체하는 데 드는 비용
Apiary의 가격은 남아있는 최고의 기능이었으므로, 마이그레이션하는 팀을 위한 공정한 비교는 목적지의 연간 청구서입니다. 정가 기준으로: Apidog는 4인까지 무료이며 이후 사용자당 월 $9, SwaggerHub Team은 사용자당 월 $34.44, ReadMe Pro는 연간 청구 시 월 $250입니다.
| 팀 규모 | Apidog 연간 | SwaggerHub Team 연간 | ReadMe Pro 연간 |
|---|---|---|---|
| 3명 | $0 (무료 플랜) | $1,240 | $3,000 |
| 5명 | $540 | $2,066 | $3,000 |
| 10명 | $1,080 | $4,133 | $3,000 |
| 25명 | $2,700 | $10,332 | $3,000 |
솔직히 말씀드리자면, 만약 하나의 사양을 무료로 렌더링할 장소만 필요하다면, 여러 문서 전용 도구에도 무료 등급이 있습니다. 위의 표는 모의 서버, 테스트 및 Apiary를 유용하게 만들었던 협업 기능이 필요한 경우에만 중요합니다. Apidog의 무료 플랜은 최대 4명까지 이 모든 것을 제공하며, 많은 Apiary 사용자에게는 마이그레이션 비용이 정확히 변환 작업에 소요되는 오후 시간과 같음을 의미합니다.
Apidog가 적합하지 않다면
"Apiary를 계속 사용하라"는 선택지가 없으므로 솔직하게 말씀드립니다.
- 문서 렌더링만 원하고 다른 것은 아무것도 원하지 않습니다. 사양이 다른 곳에서 생성되고 테스트되며, 순수하게 아름다운 호스팅 문서와 변경 로그 툴링이 필요하다면, Bump.sh(Apiary 사용자들을 위한 마이그레이션 가이드가 진정으로 훌륭합니다)와 같은 문서 우선 제품이 합리적인 착륙 지점입니다. 그곳으로 가기 위해서도 Blueprint를 OpenAPI로 변환해야 합니다.
- SmartBear 스택으로 표준화하고 있습니다. SwaggerHub는 Apiary의 호스팅 사양 레지스트리 아이디어에 가장 가까운 철학적 후손입니다. 사용자당 비용과 측정된 테스트 실행에 유의하십시오. 최고의 SwaggerHub 대안에서 이를 분석했습니다.
- 귀하의 중심은 대규모 플랫폼 팀을 위한 설계 거버넌스입니다. Stoplight는 심도 깊은 스타일 가이드 및 거버넌스 툴링을 구축했습니다. 커밋하기 전에 최고의 Stoplight 대안에서 비교 내용을 확인하십시오.
- API Blueprint에 감정적으로 애착을 가지고 있습니다. 동정하지만, 그러지 마십시오. 해당 형식의 툴링은 유지보수되지 않고 있으며, 이를 만든 회사는 서비스가 종료되고 있고, OpenAPI가 승리했습니다. 한 번 변환하고 다시는 생각하지 마십시오. 우리의 오래된 API Blueprint 가이드는 역사적인 자료로 남을 수 있습니다.
자주 묻는 질문
Apiary는 정확히 언제 종료됩니까?
Oracle은 자사 포럼에서 Apiary 지원 종료를 발표했으며, API 툴링 공급업체들의 현재 보고에 따르면 호스팅 서비스는 2026년 9월경에 종료될 예정입니다. 더 안전한 가정은 간단합니다. 지금 내보내십시오. 제품의 모든 부분이 이미 유지보수되지 않고 있기 때문입니다.
Apidog는 API Blueprint 파일을 직접 가져올 수 있습니까?
아니요. Apidog는 OpenAPI/Swagger, Postman, HAR, RAML, JMeter, apiDoc, I/O Docs, WADL, Google Discovery 형식을 가져옵니다. 먼저 api-spec-converter 또는 apib2swagger와 같은 도구를 사용하여 API Blueprint를 OpenAPI로 변환한 다음, 결과를 가져오십시오. 이는 일회성 단계이며, 나중에 인증 스키마를 수동으로 확인하십시오.
Apiary 모의 서버는 무엇으로 대체됩니까?
Apidog의 내장 스마트 모의 서버입니다. Apiary가 작성한 예시를 재생하는 반면, Apidog는 스키마에서 현실적인 응답을 자동으로 생성하며, 특정 경우에 대한 사용자 지정 모의 규칙을 정의할 수 있습니다. 가져온 모든 엔드포인트는 설정 없이 모의 엔드포인트를 얻습니다.
계약 테스트를 위한 Dredd는 무엇으로 대체됩니까?
Apidog의 자동화된 테스트 시나리오입니다. 이들은 구현에 실제 요청을 보내고 사양의 스키마에 대해 응답을 검증하며, 어설션과 Apidog CLI를 통한 CI 실행을 지원합니다. 이는 Dredd가 했던 작업을 포함하여 Dredd가 가졌던 적 없는 테스트 스위트 기능까지 포함합니다.
Apidog는 소규모 팀에게 실제로 무료입니까?
예. 무료 플랜은 최대 4명의 사용자를 지원하며, 사양 편집기, 게시된 대화형 문서, 스마트 모의 서버 및 API 테스트가 포함됩니다. 4명 이상부터는 사용자당 월 $9이며, 이는 Apiary 마이그레이션 대상 중 가장 낮은 사용자당 가격입니다.
오늘 내보내고, 아무것도 재설계하지 마십시오
작업 순서가 중요합니다. Apiary에서 먼저 내보내고, 두 번째로 Blueprint를 OpenAPI로 변환하며, 그 후에야 여유롭게 목적지를 평가하십시오. 처음 두 단계는 마감일이 있고 세 번째 단계는 마감일이 없기 때문입니다. 준비가 되면 OpenAPI 파일을 Apidog로 가져오십시오. 그러면 오후가 끝나기 전에 문서, 모의 및 테스트 하네스를 갖게 될 것입니다. Apidog를 다운로드하거나 브라우저에서 시작하십시오. 4인 팀은 비용을 지불하지 않으며, Apiary가 개척한 설계 우선 워크플로우는 마침내 그 가치에 걸맞은 유지보수되는 플랫폼을 얻게 될 것입니다.