스톱라이트에서 에이피아이독으로 마이그레이션하는 방법 (스펙 우선 워크플로우)

Stoplight Studio 또는 Stoplight Platform에서 Apidog로 이전하는 경우 가장 먼저 알아야 할 것은 OpenAPI 사양을 다시 업로드할 필요가 없다는 것입니다. Apidog의 Spec-First Mode (현재 베타)는 기존 GitHub 또는 GitLab 리포지토리에 직접 연결되므로 Git이 진실의 원천으로 유지되고 커밋 기록이 그대로 보존됩니다. 이 가이드는 Stoplight 구성을 내보내고, 해당 디렉터리 규칙을 Apidog의 기대치에 매핑하고, .stoplight.json 및 toc.json을 Apidog의 동등한 것으로 대체하는 모든 단계를 안내합니다.

World Economic Forum과 같은 팀들은 이미 문서화를 위해 Stoplight와 함께 Git에서 OpenAPI 사양을 관리하고 있습니다. 만약 이것이 여러분의 설정과 일치한다면, 이 가이드는 여러분을 위해 작성되었습니다. 그리고 아직 마이그레이션을 결정하기보다 옵션을 저울질하고 있다면, 최고의 Stoplight Studio 대안 게시물에서 더 넓은 환경을 다룹니다.

button

마이그레이션 시 변하지 않는 것

여러분의 OpenAPI 파일, Git 리포지토리, 브랜치 전략은 변하지 않습니다. 이것이 핵심 전제입니다. Stoplight는 사양을 소스 제어에 체크인된 YAML 또는 JSON 파일로 저장합니다. Apidog는 Spec-First Mode에서 리포지토리를 연결할 때 동일한 파일을 읽습니다.

변하는 것은 그 위에 겹쳐진 모든 것입니다: 문서 렌더러, 목 서버, 테스트 러너, 그리고 API 클라이언트. Stoplight Platform이 문서를 제공하고 Postman이 별도의 도구로 테스트를 처리하는 대신, Apidog는 엔지니어가 이미 커밋하고 있는 동일한 OpenAPI 파일과 동기화되어 이 모든 것을 하나의 작업 공간에 결합합니다.

실질적인 결과: 여러분의 마이그레이션은 데이터 마이그레이션이 아닌, 대부분 구성 교체입니다.

1단계: Stoplight 프로젝트 자산 내보내기

Apidog를 만지기 전에 Git에 없는 모든 Stoplight 데이터를 캡처하세요.

Git 백엔드가 있는 Stoplight Studio를 사용하는 경우:

OpenAPI 사양, JSON Schema 모델 및 Markdown 문서는 이미 커밋되어 있습니다. 로컬 복제본이 최신 상태인지 확인하려면 git pull을 실행하세요. Stoplight는 OpenAPI Specification 형식을 따르며, 이러한 사양 파일은 변환 없이 Apidog에서 작동합니다. 리포지토리 구조는 다음과 같을 것입니다:

your-api-repo/
  .stoplight.json          # 프로젝트 구성 (교체 필요)
  reference/
    petstore.yaml          # 여러분의 OpenAPI 사양
  models/
    error.json             # 공유 JSON Schema 모델
  docs/
    introduction.md        # 마크다운 가이드 페이지
    authentication.md
  toc.json                 # 목차 순서 (교체 필요)
  assets/
    images/
      architecture.png

Stoplight Platform (클라우드 호스팅, Git 백엔드 없음)을 사용하는 경우:

Stoplight UI에서 사양을 내보내세요: 각 API 프로젝트를 열고 "Export"로 이동하여 OpenAPI YAML을 다운로드하세요. Markdown 문서의 경우, 새 Git 리포지토리의 docs/ 폴더에 복사하세요. Stoplight는 Git이 아닌 프로젝트에 대한 대량 내보내기를 제공하지 않으므로, 각 API 프로젝트별로 이 작업을 수행하세요.

파일이 Git 리포지토리(GitHub 또는 GitLab)에 있으면 다음 단계로 진행하세요.

2단계: 교체할 구성 파일 이해

두 개의 Stoplight 특정 파일이 프로젝트 구조를 구동합니다. 둘 다 Apidog에 직접적인 대응은 없지만, 이들이 하는 일을 이해하면 Apidog에서 대신 구성할 내용이 무엇인지 정확히 알 수 있습니다.

Stoplight 파일	역할	Apidog 동등 항목
`.stoplight.json`	프로젝트 루트, 사양 경로, 문서 경로 및 프로젝트에 포함된 파일을 선언합니다.	Apidog 프로젝트 내의 리포지토리 연결 설정 (파일이 아닌 UI를 통해 구성)
`toc.json`	Stoplight 문서 사이드바에서 페이지의 순서와 그룹화를 제어합니다.	Apidog는 디렉터리 구조를 읽고, 사이드바 순서는 Apidog 문서 편집기에서 설정됩니다 (단일 파일 아님).
`reference/` 규칙	Stoplight가 OpenAPI 사양 파일을 예상하는 위치입니다.	Apidog Spec-First Mode에서 구성 가능; 기본값은 리포지토리 루트이지만 `reference/`를 가리키도록 설정할 수 있습니다.
`models/` 규칙	공유 구성 요소를 위한 JSON Schema 파일입니다.	OpenAPI 사양의 `components/schemas` 섹션에서 참조; Apidog는 `$ref` 경로를 확인합니다.
`docs/` 규칙	마크다운 가이드 페이지입니다.	Apidog에서 문서 페이지로 가져오기; 디렉터리 계층 구조는 사이드바 섹션에 매핑됩니다.

핵심 통찰: .stoplight.json과 toc.json은 Stoplight 독점 파일입니다. 이들을 리포지토리에 남겨둘 수 있지만(Apidog는 알 수 없는 파일을 무시합니다), Apidog에서는 아무것도 구동하지 않습니다. 동등한 설정은 Apidog 프로젝트 UI를 통해 구성합니다.

3단계: 리포지토리를 Apidog Spec-First Mode에 연결

Apidog Spec-First Mode는 GitHub 또는 GitLab 리포지토리를 Apidog 프로젝트에 연결하여 OpenAPI 사양이 Apidog 내부 데이터베이스가 아닌 Git에서 항상 읽히도록 하는 방법입니다. 이는 Git을 권한 있는 소스로 유지하며, 엔지니어들이 오늘날과 동일하게 사양 업데이트를 위해 PR을 계속 제출할 수 있음을 의미합니다.

다음은 연결 흐름입니다. OAuth 권한 부여에 대해 확신이 없다면 GitHub의 타사 앱을 리포지토리에 연결하는 문서를 검토할 수도 있습니다.

Apidog에서 새 프로젝트 **Spec-First Mode**를 생성합니다.
Apidog를 GitHub 또는 GitLab 계정으로 인증하고 리포지토리를 선택합니다.

3. **브랜치**를 설정합니다: 프로덕션 사양에는 기본 브랜치(main 또는 master)를 사용하고, 마이그레이션 테스트 중에는 피처 브랜치를 사용합니다.

저장합니다. Apidog는 사양을 읽고 대화형 문서, 목 서버 엔드포인트 및 테스트 스캐폴딩을 빌드합니다.

사양이 $ref를 사용하여 models/ 디렉터리에서 스키마를 가져오는 경우, Apidog는 사양 파일 위치를 기준으로 해당 참조를 확인합니다. OpenAPI 파일의 경로가 올바르다면 추가 구성이 필요하지 않습니다. 이 Git 동기화가 작동하는 방식에 대한 자세한 내용은 GitHub로 OpenAPI 사양 동기화 가이드에서 자세히 설명합니다.

4단계: Markdown 문서 마이그레이션

Stoplight는 Markdown 가이드 페이지를 API 참조 문서와 함께 단일 사이드바에 혼합할 수 있습니다. Apidog도 문서 편집기를 통해 동일한 작업을 수행합니다.

리포지토리를 연결한 후, docs/ Markdown 파일을 가져옵니다:

Apidog 프로젝트에서 **Docs** 섹션을 엽니다.
**Import > Markdown**을 사용하여 파일을 업로드하거나, 페이지별로 내용을 붙여넣습니다.

Markdown에서 참조된 이미지 자산(일반적인 Stoplight 레이아웃의 assets/images/ 폴더)의 경우, Apidog의 파일 저장소에 업로드하고 각 페이지의 ![alt](path) 참조를 업데이트하세요. 이미지가 이미 CDN 또는 공용 URL에 호스팅되어 있다면 아무것도 변경할 필요가 없습니다.

5단계: Stoplight의 목 서버 교체

Stoplight Studio에는 OpenAPI 사양을 읽고 예시 응답을 반환하는 로컬 목 서버가 포함되어 있습니다. Apidog의 목 서버도 동일한 작업을 수행하지만, 클라우드에 호스팅되어 로컬 프로세스를 실행할 필요 없이 전체 팀이 액세스할 수 있습니다.

Spec-First Mode를 통해 사양이 연결되면, Apidog는 OpenAPI 파일에 정의된 모든 작업에 대해 목 엔드포인트를 자동으로 생성합니다. 예시 응답은 사양의 examples 필드에서 가져오거나, 예시가 정의되지 않은 경우 Apidog의 스마트 목 엔진에서 가져옵니다. 사양 파일을 건드리지 않고도 Apidog 내에서 엔드포인트별 응답 규칙을 재정의할 수 있습니다.

stoplight mock reference/your-api.yaml을 로컬에서 실행하는 데 익숙한 팀의 경우, QA 엔지니어와 프론트엔드 개발자가 이제 공유 클라우드 URL에 접속한다는 점이 달라집니다. 이는 네트워크 액세스 정책에 적합한지 확인하기 위해 시험적으로 검증할 가치가 있습니다.

6단계: 테스트 스위트 재구성

Stoplight의 계약 테스트 또는 린팅을 위한 Spectral 규칙을 사용했다면, 별도의 처리가 필요합니다.

Spectral 린트 규칙: Stoplight는 .spectral.yaml 파일을 통해 구성된 OpenAPI 린팅을 위해 Spectral을 사용합니다. Apidog는 OpenAPI 준수를 위한 자체 내장 린트 규칙을 가지고 있지만, Spectral을 직접 실행하지는 않습니다. 팀이 의존하는 사용자 지정 Spectral 규칙이 있다면, Apidog와 독립적으로 CI(GitHub Actions 또는 GitLab CI)에서 계속 실행하세요. Apidog의 린트 범위와 사용자 지정 린트 규칙 세트를 프로젝트 간에 공유할 수 있는지 여부는 특정 규칙 요구 사항에 대해 시험적으로 확인해 볼 가치가 있습니다.

API 테스트: Stoplight Platform에는 시나리오 기반 API 테스트가 포함되어 있습니다. Apidog의 테스트 러너를 사용하면 테스트 시나리오를 시각적으로 구축하고, 요청을 연결하고, 응답 본문, 헤더 및 상태 코드에 대해 어설션을 실행할 수 있습니다. Stoplight 테스트 프로젝트에서 자동 가져오기 기능은 없으므로 Apidog 내에서 이들을 다시 구축해야 합니다. Git 기반 API 워크플로 가이드는 Apidog 테스트 실행을 GitHub Actions 파이프라인에 통합하는 방법을 보여줍니다.

예시: Stoplight 테스트가 POST /orders가 location 헤더와 함께 201을 반환하는지 확인했다면, Apidog CLI를 사용하는 CI 파이프라인에서 동등한 Apidog 테스트 설정은 다음과 같습니다:

# .github/workflows/api-tests.yml
name: API contract tests

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Apidog tests
        run: |
          npx apidog-cli run \
            --project-id ${{ secrets.APIDOG_PROJECT_ID }} \
            --test-id ${{ secrets.APIDOG_TEST_SUITE_ID }} \
            --env production \
            --reporter junit \
            --output test-results.xml
        env:
          APIDOG_API_KEY: ${{ secrets.APIDOG_API_KEY }}

      - name: Publish test results
        uses: mikepenz/action-junit-report@v4
        if: always()
        with:
          report_paths: test-results.xml

이는 CI에서 Stoplight 테스트 실행을 대체하고 기존 GitHub Actions 구조를 그대로 유지합니다.

엔터프라이즈 팀을 위한 평가 체크리스트

더 큰 팀(Studio가 아닌 Stoplight Platform을 평가하는 유형)을 위해 마이그레이션하는 경우, 커밋하기 전에 확인해야 할 특정 기능이 있습니다. Apidog는 이러한 영역을 다루지만, 정확한 동작은 계획 및 작업 공간 구성에 따라 달라집니다.

기능	Apidog 평가판에서 확인할 사항
비공개 문서 액세스	인증된 사용자 또는 특정 이메일 도메인으로 문서 페이지를 제한할 수 있습니까? 액세스 제어 요구 사항에 대해 확인하십시오.
프로젝트 간 스키마/구성 요소 재사용	공유 `components/schemas` 라이브러리를 복사-붙여넣기 없이 여러 Apidog 프로젝트에서 참조할 수 있습니까? 실제 스키마 파일로 테스트할 가치가 있습니다.
사용자 지정 린트 규칙 공유	동일한 작업 공간 내의 여러 Apidog 프로젝트에서 공유 린트 프로필 (공유 `.spectral.yaml`과 동등)을 배포할 수 있습니까?
SSO/SCIM 프로비저닝	Apidog의 SSO가 여러분의 ID 공급자를 지원합니까? SCIM 프로비저닝의 세분성이 사용자 수명 주기 관리 프로세스에 적합한지 확인하십시오.
감사 로그	감사 로그가 어떤 이벤트를 어떤 형식으로 캡처합니까? 규정 준수 또는 보안 검토 요구 사항을 충족하는지 확인하십시오.

이것들을 장애물이 아닌 평가 과제로 보십시오. 대부분은 대표적인 프로젝트로 2주 평가판에서 확인할 수 있습니다.

FAQ

Apidog와 함께 Spectral을 계속 사용할 수 있습니까?

네. CI 파이프라인에서 Apidog와 독립적으로 Spectral을 실행하세요. .spectral.yaml 파일은 리포지토리에 그대로 유지되며, CI 작업(GitHub Actions, GitLab CI)은 모든 PR에서 OpenAPI 파일을 린트합니다. Apidog는 문서화, 목킹 및 테스트를 처리하고, Spectral은 린팅을 처리합니다. 서로 충돌하지 않습니다. CI 통합 옵션에 대해서는 Spectral 문서를 참조하세요.

리포지토리를 Apidog에 연결할 때 `$ref` 경로가 깨집니까?

사양 파일의 경로가 올바르다면 그렇지 않습니다. Apidog는 루트 OpenAPI 파일의 위치를 기준으로 $ref를 확인합니다. 사양이 $ref: '../models/error.json'이고 models/ 폴더가 reference/보다 한 단계 위에 있다면, Apidog는 리포지토리에서 해당 상대 경로를 따릅니다. 먼저 외부 참조를 사용하는 사양으로 테스트해 보세요.

Apidog Spec-First Mode는 GitHub뿐만 아니라 GitLab도 지원합니까?

네, GitHub와 GitLab 모두 지원됩니다. 연결 흐름은 동일합니다. GitLab 계정으로 인증하고 리포지토리와 브랜치를 선택합니다. 버전 제어 옵션에 대한 자세한 내용은 Git을 사용한 OpenAPI 버전 제어 가이드에서 브랜치 전략을 자세히 다룹니다.

마이그레이션 후 기존 Stoplight 문서 URL은 어떻게 됩니까?

Stoplight 구독을 취소하면 Stoplight 호스팅 문서 URL (docs.stoplight.io/your-org/your-api)은 작동을 멈춥니다. Apidog는 구성하는 서브도메인에 새 문서 URL을 제공합니다. 외부 링크가 Stoplight 문서 페이지를 가리키는 경우 DNS 또는 CDN 계층에서 리디렉션을 설정하세요.

리포지토리에서 `.stoplight.json` 및 `toc.json`을 삭제해야 합니까?

아니요. Apidog는 인식하지 못하는 파일을 무시합니다. 제거하면 병합 충돌이나 혼란을 야기할 수 있으므로 그대로 두세요. 팀이 Apidog로 완전히 전환되면 정리 PR에서 삭제할 수 있지만, 마이그레이션이 작동하는 데 필수적인 것은 아닙니다.

결론

Stoplight에서 Apidog로 마이그레이션하는 것은 처음부터 시작하는 것을 의미하지 않습니다. OpenAPI 사양은 Git에 그대로 유지되고, 브랜치 워크플로는 손상되지 않으며, reference/, models/, docs/ 디렉터리 구조는 Apidog가 예상하는 것과 깔끔하게 매핑됩니다. 마이그레이션은 구성 교체입니다: .stoplight.json 및 toc.json을 Apidog 프로젝트 설정으로 교체하고, Spec-First Mode를 통해 리포지토리를 연결하고, Apidog의 테스트 러너 내에서 테스트 시나리오를 다시 구축하세요.

Apidog Spec-First Mode를 기존 GitHub 또는 GitLab OpenAPI 리포지토리에 연결하여 Stoplight 마이그레이션을 시작하세요. 재업로드, 종속성, Git 기록 모두 동일하게 유지됩니다. Apidog를 다운로드하여 시작하고, 대표적인 API 프로젝트를 사용하여 실제 데이터로 위 평가 체크리스트를 확인해 보세요.