Docs-as-Code 워크플로우를 유지하면서 Redocly에서 Apidog로 마이그레이션하는 방법

Redocly에서 개발자 포털을 운영하고 있다면, 이미 대부분의 API 팀이 원하는 방식으로 일하고 있는 것입니다. openapi.yaml은 Git에 있고, 가이드는 Markdown이며, 푸시하면 문서가 업데이트됩니다. 도구를 바꿀 때 두려운 점은 바로 그 흐름을 잃고 웹 UI에서 문서를 손으로 편집하게 되는 것입니다.

그럴 필요는 없습니다. Apidog Spec-first Mode는 스펙과 Markdown을 같은 저장소에 유지하고, 웹훅을 통해 푸시할 때마다 동기화하며, 가이드와 API 레퍼런스를 하나의 사이드바에 담은 포털을 게시합니다. 이 가이드는 마이그레이션 과정을 단계별로 안내하며, 자동으로 넘어가지 않는 한 가지 부분, 즉 많은 Redocly 사용자가 info.description과 tags[].description 안에 보관하는 장문 콘텐츠까지 다룹니다.

아직 도구를 비교 중이라면 Apidog vs. Redocly 또는 더 폭넓은 Redocly 대안 목록부터 시작하세요. 이 글은 Apidog를 선택했고 워크플로를 깨뜨리지 않고 이전하고 싶다는 전제로 작성되었습니다.

무엇이 그대로 넘어오고 무엇이 그렇지 않은가

우리는 실제 프로덕션 스펙으로 이 마이그레이션을 테스트했습니다. OpenAPI 3.0.3, 13개 태그에 걸친 62개 오퍼레이션이며, 시작하기, 인증, 통합 콘텐츠가 스펙의 description 필드에 작성되어 있었습니다. 임포트 시 어떤 일이 일어났는지는 다음과 같습니다.

API 레퍼런스는 수정 없이 그대로 넘어옵니다. 빠지는 것은 서술형 콘텐츠입니다.

description 필드가 같은 방식으로 렌더링되지 않는 이유

Redocly의 레퍼런스 문서를 구동하는 렌더러인 Redoc은 info.description을 하나의 미니 문서로 취급합니다. 그 안의 모든 Markdown 제목이 사이드바 항목이 되므로, 팀들은 흔히 "시작하기"와 "인증" 가이드 전체를 그곳에 작성합니다. 태그 설명은 각 태그 그룹 상단에 소개 텍스트로 렌더링됩니다.

이것은 Redoc의 관례일 뿐 OpenAPI 명세의 일부가 아닙니다. 명세는 description을 CommonMark 문자열로 정의할 뿐입니다. 대부분의 포털과 마찬가지로 Apidog는 가이드를 독립적인 Markdown 문서로 유지하고, 레퍼런스를 위해 스펙을 유지합니다. 임포트 후 기본 게시는 description 필드에 작성한 가이드 없이 API 레퍼런스만 보여줍니다.

해결책은 일회성 이동입니다. 그 콘텐츠를 YAML에서 꺼내 옆에 있는 Markdown 파일로 옮기는 것입니다. 그 이후로는 모든 것이 Git 기반으로 유지됩니다.

목표 저장소 레이아웃

우리가 검증한 구조는 다음과 같습니다.

your-repo/
├── openapi.yaml              # API 레퍼런스의 소스 오브 트루스
└── docs/
    ├── getting-started.md
    ├── authentication.md
    └── embed-integration-guide.md

openapi.yaml이 API 레퍼런스를 구동합니다. docs/의 각 파일은 포털 사이드바의 페이지가 됩니다. 해당 Markdown 파일이 참조하는 이미지는 같은 저장소에 두고 함께 동기화할 수 있습니다.

Redocly의 sidebars.yaml로 내비게이션 순서를 지정했다면 참고용으로 보관하세요. Apidog의 문서 사이트 설정에서 같은 순서를 한 번만 지정하면 됩니다.

단계별 마이그레이션

1. description 필드 안에 무엇이 있는지 점검하세요

무엇이든 옮기기 전에 스펙에 얼마나 많은 콘텐츠가 들어 있는지 확인하세요. yq를 사용하면 다음과 같습니다.

# How long is the top-level description?
yq '.info.description' openapi.yaml | wc -w

# Which headings does it contain? Each one is a Redoc sidebar entry today.
yq '.info.description' openapi.yaml | grep -E '^#{1,3} '

# Which tags carry a description?
yq '.tags[] | select(.description != null) | .name' openapi.yaml

제목 목록이 앞으로 만들 docs/ 파일 목록이 됩니다. 우리 테스트에서는 info.description이 두 개의 Markdown 파일로 나뉘었고, 태그 설명은 폴더별 소개 페이지와 추가 Markdown 파일 하나가 되었습니다.

2. info.description을 Markdown 파일로 분할하세요

각 최상위 섹션을 docs/ 아래의 개별 파일로 복사하세요. 제목, 코드 샘플, 링크는 유지합니다. 그런 다음 스펙의 info.description을 한 문단 요약으로 줄여서 콘텐츠가 한 곳에만 존재하도록 하세요.

복사할 때 Redoc 특유의 기능 두 가지에 주의하세요.

• <SecurityDefinitions /> 및 이와 유사한 Redoc 태그는 Redoc 외부에서는 렌더링되지 않습니다. 이를 레퍼런스의 보안 스킴으로 연결되는 짧은 서술 섹션으로 교체하세요.
• #tag/Payments 같은 링크는 Redoc 앵커를 가리킵니다. 첫 게시 후 해당하는 Apidog 문서나 폴더 URL로 업데이트하세요.

3. Spec-first Mode에서 저장소를 연결하세요

Spec-first Mode에서 프로젝트를 만들고, 저장소(GitHub, GitLab, Azure DevOps 또는 Bitbucket)를 연결하고, openapi.yaml과 docs/ 폴더를 지정한 뒤 웹훅을 설치하세요. 그 이후로는 추적 중인 브랜치에 푸시하면 프로젝트가 업데이트됩니다.

첫 동기화 후 Specs 워크스페이스에 스펙과 저장소의 나머지가 표시됩니다. APIs 탭에는 openapi.yaml에서 파싱된 오퍼레이션이 나열되고, Docs에는 Markdown 페이지가 담기며, All files는 저장소를 그대로 반영합니다.

이것을 docs-as-code 워크플로로 유지해 주는 것이 바로 웹훅입니다. 웹훅이 없으면 동기화를 수동으로 트리거해야 합니다. 이것이 왜 중요한지 다시 알고 싶다면 docs as code 가이드를 참고하세요.

4. 문서 사이트를 게시하고 내비게이션을 설정하세요

프로젝트에서 문서 사이트를 게시하고 사이드바를 구성하세요. 대부분의 Redocly 사용자가 원하는 순서이자 우리가 재현한 순서는 다음과 같습니다.

1. 시작하기
2. 인증
3. 통합 가이드
4. API 레퍼런스 (태그에서 생성된 엔드포인트 폴더)

Markdown 페이지와 API 폴더는 하나의 트리에서 자유롭게 섞이므로 현재 Redocly 사이드바와 거의 동일하게 맞출 수 있습니다.

5. 사용자 지정 도메인을 추가하세요

developers.example.com 같은 CNAME을 문서 사이트로 지정하세요. 사용자 지정 도메인은 Free 플랜에서도 사용할 수 있습니다.

Apidog CLI로 코딩 에이전트가 태그 설명을 마이그레이션하게 하세요

태그 설명이 가장 지루한 부분입니다. 태그가 13개면 복사-붙여넣기 작업이 13번이고, 전환 중에 태그 설명이 바뀔 때마다 다시 해야 합니다. 대신 코딩 에이전트에게 맡기세요.

Apidog CLI는 Claude Code, Codex, Cursor 또는 모든 터미널 에이전트에 엔드포인트 폴더를 포함한 프로젝트 리소스에 대한 구조화된 JSON 접근을 제공합니다. 한 번만 설정하세요.

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_ACCESS_TOKEN>
npx -y skills add https://apidog.com

마지막 줄은 Apidog 스킬을 설치하여 에이전트가 명령을 추측하지 않고 알 수 있게 합니다. 설치 가이드에서 토큰과 프라이빗 배포를 다룹니다.

그런 다음 에이전트에게 프롬프트 하나를 주세요.

openapi.yaml을 읽어라. 설명이 있는 모든 태그에 대해 Apidog 프로젝트 <PROJECT_ID>에서 일치하는 엔드포인트 폴더를 찾아 그 폴더의 설명을 태그의 설명으로 설정하라. 쓰기 전에 각 페이로드를 apidog cli-schema validate folder-update로 검증하라. 변경한 폴더 목록을 보여달라.

에이전트가 실행하는 내용은 다음과 같습니다.

# Find the folder IDs that correspond to your tags
apidog folder list --project <PROJECT_ID> --type endpoint

# Check the payload shape instead of guessing it
apidog cli-schema get folder-update

# For each tag: write {"description": "..."} to a file, validate, then update
apidog cli-schema validate folder-update --file ./payments-folder.json
apidog folder update <FOLDER_ID> --project <PROJECT_ID> --type endpoint \
  --file ./payments-folder.json

folder-update 스키마는 name, parentId, description을 허용하며, description은 엔드포인트 폴더와 테스트 시나리오 폴더에서 지원됩니다. 단일 태그에 속하지 않는 가이드의 경우, 에이전트는 apidog doc list와 apidog doc create를 같은 방식으로 사용할 수 있으며, 이때 apidog cli-schema get doc-create를 먼저 읽습니다.

게시된 사이트에서 폴더의 소개를 표시하려면 폴더 설정의 Documentation Settings after Publication에서 Folder Contents Displaying Setting을 설정하세요.

솔직한 단서 하나: 태그 설명을 카테고리별 소개 페이지로 노출하는 것은 작동하지만, 문서화가 덜 된 경로에 의존합니다. 모든 폴더에서 이것에 의존하기 전에 자신의 워크스페이스에서 두세 개 폴더로 테스트해 보세요. 더 많은 에이전트 기반 스펙 작업은 Claude Code에서 Apidog CLI 사용하기와 에이전트가 API 스펙을 업데이트하게 하기를 참고하세요.

Git 밖에 남는 것

Spec-first 프로젝트는 API와 Markdown을 Git에 유지합니다. 몇 가지 포털 설정은 Apidog 인터페이스에 있으며 버전 관리되지 않습니다.

이것들은 한 번만 설정하는 항목입니다. 새 최상위 섹션을 추가할 때 건드리는 것이지, 콘텐츠를 변경할 때마다 건드리는 것이 아닙니다. Redocly는 이 중 더 많은 것을 redocly.yaml과 sidebars.yaml에 보관하므로, 오늘날 풀 리퀘스트에서 내비게이션 변경을 검토한다면 그것이 UI로 이동할 것이라는 점을 계획에 넣으세요.

플랜 및 가격

여기서 설명한 설정은 사용자 지정 도메인을 포함해 Free 플랜에 맞습니다. Free는 최대 4명의 팀원까지 지원합니다. 유료 플랜은 프로젝트당 여러 문서 사이트, 사용자 지정 공개 범위 제어 같은 것을 추가합니다. 현재 한도는 Apidog 가격을 확인하세요.

마이그레이션 후 Redocly vs. Apidog

트레이드오프는 단순합니다. YAML로 정의된 내비게이션을 잃습니다. 대신 문서가 나오는 같은 스펙 위에서 테스트, 모킹, 에이전트 친화적 CLI를 얻습니다. CLI 대 CLI 비교는 Apidog CLI vs Redocly CLI를 읽어보세요.

FAQ

Redocly에서 호스팅하던 URL이 계속 작동하나요? 자동으로는 아닙니다. 페이지 경로가 바뀝니다. 기존 포털에 트래픽이 많은 가이드 URL이 있었다면, 도메인을 전환한 후 주요 페이지에 대해 DNS나 프록시 계층에서 리디렉션을 추가하세요.

OpenAPI 스펙을 다시 작성해야 하나요? 아닙니다. 스펙은 그대로 임포트됩니다. 서술형 콘텐츠를 info.description과 tags[].description에서 Markdown 파일로 옮기기만 하면 됩니다.

x-tagGroups를 유지할 수 있나요? 대신 폴더로 그룹화하세요. 각 태그가 폴더가 되고, 폴더를 중첩하여 태그 그룹을 재현할 수 있습니다.

Stoplight에서 마이그레이션하는 것과 비교하면 어떤가요? 형태는 비슷합니다. 스펙은 Git에, Markdown은 옆에, 웹훅 동기화. 두 도구를 모두 운영한다면 Stoplight에서 Apidog로 마이그레이션하는 방법을 참고하세요.

내 워크스페이스에서 단계가 다르게 동작하면 어떻게 하나요? 우리 결과는 테스트 환경에서 나온 것입니다. DNS를 전환하기 전에 먼저 브랜치에서 임포트를 다시 실행하고 게시된 포털을 현재 포털과 비교하세요.

오후 한나절에 이동을 끝내세요

Redocly에서 Apidog로의 마이그레이션은 대부분 콘텐츠 이동입니다. 스펙은 그대로 임포트됩니다. 가이드는 description 필드에서 docs/ 폴더로 한 번만 옮깁니다. 그 후에는 웹훅이 모든 것을 동기화 상태로 유지합니다. 반복적인 태그 설명 작업은 Apidog CLI로 에이전트가 처리하게 하고, 자신의 시간은 게시된 포털을 페이지별로 확인하는 데 쓰세요.

Apidog 다운로드하고 저장소를 Spec-first Mode에 연결하여 마이그레이션을 시작하세요.