DEV Community

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

Posted on • Originally published at apidog.com

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

Stoplight Studio 또는 Stoplight Platform에서 Apidog로 이전할 때 핵심은 OpenAPI 사양을 다시 업로드하지 않아도 된다는 점입니다. Apidog의 Spec-First Mode(현재 베타)는 기존 GitHub 또는 GitLab 리포지토리에 직접 연결되므로 Git을 단일 진실 공급원으로 유지하고 커밋 기록도 그대로 보존할 수 있습니다.

오늘 Apidog를 사용해 보세요

World Economic Forum과 같은 팀들도 이미 Git에서 OpenAPI 사양을 관리하고 Stoplight를 문서화에 사용해 왔습니다. 여러분의 환경도 비슷하다면, 이 가이드는 Stoplight 구성 내보내기, 디렉터리 규칙 매핑, .stoplight.json 및 toc.json을 Apidog 설정으로 대체하는 과정을 단계별로 설명합니다. 아직 도구를 비교 중이라면 최고의 Stoplight Studio 대안도 함께 확인해 보세요.

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

마이그레이션해도 다음은 그대로 유지됩니다.

  • OpenAPI YAML/JSON 파일
  • GitHub 또는 GitLab 리포지토리
  • 브랜치 전략
  • PR 기반 사양 변경 흐름
  • 기존 커밋 기록

Stoplight는 OpenAPI 사양을 소스 제어에 체크인된 YAML 또는 JSON 파일로 저장합니다. Apidog는 Spec-First Mode에서 같은 파일을 읽습니다.

변하는 것은 사양 위에서 동작하는 도구입니다.

  • 문서 렌더러
  • 목 서버
  • 테스트 러너
  • API 클라이언트
  • 프로젝트 구성 방식

Stoplight Platform이 문서를 제공하고 Postman 같은 별도 도구가 테스트를 처리했다면, Apidog는 동일한 OpenAPI 파일을 기준으로 문서화, 목킹, 테스트, API 클라이언트를 하나의 작업 공간에서 제공합니다.

실제로 이 마이그레이션은 데이터 이전이라기보다 구성 교체 작업에 가깝습니다.

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

먼저 Git에 없는 Stoplight 데이터를 모두 확보하세요.

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

OpenAPI 사양, JSON Schema 모델, Markdown 문서는 이미 리포지토리에 커밋되어 있을 가능성이 높습니다.

로컬 복제본을 최신 상태로 맞춥니다.

git pull
Enter fullscreen mode Exit fullscreen mode

Stoplight는 OpenAPI Specification 형식을 따르므로, 사양 파일은 변환 없이 Apidog에서 사용할 수 있습니다.

일반적인 리포지토리 구조는 다음과 같습니다.

your-api-repo/
  .stoplight.json          # Stoplight 프로젝트 구성, Apidog에서는 교체 대상
  reference/
    petstore.yaml          # OpenAPI 사양
  models/
    error.json             # 공유 JSON Schema 모델
  docs/
    introduction.md        # Markdown 가이드 페이지
    authentication.md
  toc.json                 # Stoplight 목차 순서, Apidog에서는 교체 대상
  assets/
    images/
      architecture.png
Enter fullscreen mode Exit fullscreen mode

Git 백엔드가 없는 Stoplight Platform을 사용하는 경우

Stoplight UI에서 각 API 프로젝트를 열고 Export 메뉴를 통해 OpenAPI YAML을 다운로드하세요.

Markdown 문서는 새 Git 리포지토리의 docs/ 폴더에 복사합니다.

new-api-repo/
  reference/
    api.yaml
  docs/
    introduction.md
    authentication.md
  assets/
    images/
Enter fullscreen mode Exit fullscreen mode

Stoplight는 Git이 아닌 프로젝트에 대해 대량 내보내기를 제공하지 않으므로, API 프로젝트별로 반복해야 합니다.

파일이 GitHub 또는 GitLab 리포지토리에 준비되면 다음 단계로 이동합니다.

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

Stoplight 프로젝트에서 중요한 구성 파일은 두 가지입니다.

Stoplight 파일 역할 Apidog에서의 대응 방식
.stoplight.json 프로젝트 루트, 사양 경로, 문서 경로, 포함 파일을 선언합니다. Apidog 프로젝트의 리포지토리 연결 설정에서 구성합니다. 파일 기반이 아니라 UI 기반입니다.
toc.json Stoplight 문서 사이드바의 페이지 순서와 그룹을 제어합니다. Apidog 문서 편집기에서 사이드바 순서를 설정합니다.
reference/ Stoplight가 OpenAPI 사양 파일을 찾는 기본 위치입니다. Apidog Spec-First Mode에서 사양 경로로 지정할 수 있습니다.
models/ 공유 JSON Schema 파일을 저장합니다. OpenAPI의 components/schemas 또는 $ref 경로를 통해 참조합니다.
docs/ Markdown 가이드 페이지를 저장합니다. Apidog Docs로 가져오거나 페이지별로 복사합니다.

핵심은 .stoplight.json과 toc.json이 Stoplight 전용 파일이라는 점입니다.

Apidog는 이 파일들을 사용하지 않습니다. 리포지토리에 남겨 두어도 Apidog는 알 수 없는 파일을 무시합니다. 마이그레이션 중에는 삭제하지 말고, 전환이 끝난 뒤 정리 PR에서 제거하는 편이 안전합니다.

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

Apidog Spec-First Mode는 GitHub 또는 GitLab 리포지토리를 Apidog 프로젝트에 연결하여 OpenAPI 사양을 Apidog 내부 DB가 아니라 Git에서 읽도록 하는 방식입니다.

즉, 기존처럼 엔지니어가 PR로 사양을 변경하고, Git을 권한 있는 소스로 유지할 수 있습니다.

연결 절차는 다음과 같습니다.

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

Apidog Spec-First Mode repository selection

  1. 사용할 브랜치를 선택합니다.
    • 운영 사양: main 또는 master
    • 마이그레이션 테스트: 별도 feature 브랜치
  2. 저장합니다.

Apidog branch configuration

저장 후 Apidog는 OpenAPI 사양을 읽고 다음을 생성합니다.

  • 대화형 API 문서
  • 목 서버 엔드포인트
  • 테스트 스캐폴딩
  • API 요청 컬렉션

사양이 models/ 디렉터리의 스키마를 $ref로 참조하는 경우, Apidog는 OpenAPI 파일 위치를 기준으로 상대 경로를 해석합니다.

예를 들어 다음 구조라면:

your-api-repo/
  reference/
    api.yaml
  models/
    error.json
Enter fullscreen mode Exit fullscreen mode

reference/api.yaml에서 다음처럼 참조할 수 있습니다.

components:
  schemas:
    Error:
      $ref: ../models/error.json
Enter fullscreen mode Exit fullscreen mode

경로가 올바르면 추가 설정은 필요하지 않습니다. Git 동기화 방식은 GitHub로 OpenAPI 사양 동기화 가이드에서도 확인할 수 있습니다.

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

Stoplight는 Markdown 가이드 페이지와 API 참조 문서를 하나의 사이드바에 함께 표시할 수 있습니다. Apidog도 Docs 기능을 통해 비슷한 구조를 만들 수 있습니다.

리포지토리를 연결한 뒤 docs/ 폴더의 Markdown 파일을 가져옵니다.

  1. Apidog 프로젝트에서 Docs 섹션을 엽니다.
  2. Import > Markdown을 선택합니다.
  3. Markdown 파일을 업로드하거나 페이지별로 내용을 붙여넣습니다.
  4. 사이드바에서 문서 순서를 재구성합니다.

Apidog Markdown import

Markdown 안에서 이미지가 상대 경로를 사용하고 있다면 확인이 필요합니다.

예:

![Architecture](../assets/images/architecture.png)
Enter fullscreen mode Exit fullscreen mode

이미지가 assets/images/ 같은 로컬 폴더에 있다면 Apidog 파일 저장소에 업로드한 뒤 이미지 경로를 업데이트하세요.

![Architecture](https://your-uploaded-image-url)
Enter fullscreen mode Exit fullscreen mode

이미지가 이미 CDN 또는 공용 URL에 있다면 수정하지 않아도 됩니다.

5단계: Stoplight 목 서버 교체하기

Stoplight Studio는 OpenAPI 사양을 읽고 예시 응답을 반환하는 로컬 목 서버를 제공합니다.

기존에는 다음과 같이 실행했을 수 있습니다.

stoplight mock reference/your-api.yaml
Enter fullscreen mode Exit fullscreen mode

Apidog의 목 서버도 OpenAPI 사양을 기반으로 응답을 생성하지만, 로컬 프로세스가 아니라 클라우드에서 호스팅됩니다. 따라서 프론트엔드 개발자와 QA 엔지니어가 같은 목 서버 URL을 공유할 수 있습니다.

Spec-First Mode로 사양을 연결하면 Apidog는 OpenAPI에 정의된 작업별로 목 엔드포인트를 생성합니다.

응답 생성 기준은 다음과 같습니다.

  1. OpenAPI 사양의 examples
  2. 예시가 없을 경우 Apidog의 스마트 목 엔진
  3. 엔드포인트별로 Apidog에서 설정한 응답 규칙

예를 들어 사양에 다음 응답 예시가 있으면:

paths:
  /orders:
    post:
      responses:
        '201':
          description: Order created
          content:
            application/json:
              examples:
                success:
                  value:
                    id: ord_123
                    status: created
Enter fullscreen mode Exit fullscreen mode

Apidog 목 서버는 해당 예시를 기반으로 응답을 반환할 수 있습니다.

마이그레이션 전에 다음을 검증하세요.

  • 팀원이 공유 목 URL에 접근할 수 있는지
  • 사내 네트워크 정책에 맞는지
  • 인증이 필요한 엔드포인트의 목 응답 규칙이 충분한지
  • 프론트엔드 개발 환경에서 기존 로컬 목 서버 URL을 Apidog 목 URL로 교체할 수 있는지

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

Stoplight에서 계약 테스트, 시나리오 테스트 또는 Spectral 린팅을 사용했다면 별도로 이전 계획을 세워야 합니다.

Spectral 린트 규칙 유지하기

Stoplight는 OpenAPI 린팅에 Spectral을 사용합니다. 일반적으로 .spectral.yaml로 규칙을 구성합니다.

Apidog는 OpenAPI 준수를 위한 자체 린트 기능을 제공하지만, Spectral을 직접 실행하지는 않습니다.

따라서 사용자 지정 Spectral 규칙이 있다면 CI에서 계속 실행하세요.

예: GitHub Actions에서 Spectral 유지

# .github/workflows/openapi-lint.yml
name: OpenAPI lint

on:
  pull_request:
    branches: [main]

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

      - name: Install Spectral
        run: npm install -g @stoplight/spectral-cli

      - name: Lint OpenAPI spec
        run: spectral lint reference/api.yaml
Enter fullscreen mode Exit fullscreen mode

이렇게 하면 역할을 분리할 수 있습니다.

  • Apidog: 문서화, 목킹, API 테스트
  • Spectral: 사용자 지정 OpenAPI 린팅

API 테스트 재구성하기

Stoplight Platform의 시나리오 기반 API 테스트는 Apidog로 자동 가져오기되지 않습니다. Apidog 테스트 러너에서 다시 구성해야 합니다.

Apidog에서는 다음을 시각적으로 설정할 수 있습니다.

  • 요청 순서
  • 요청 간 데이터 전달
  • 상태 코드 검증
  • 응답 헤더 검증
  • 응답 본문 검증
  • 환경 변수

예를 들어 Stoplight 테스트가 다음 조건을 검증했다면:

  • POST /orders
  • 응답 상태 코드: 201
  • 응답 헤더: location 존재

Apidog에서 같은 시나리오를 만든 뒤 CI에서 실행할 수 있습니다.

# .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
Enter fullscreen mode Exit fullscreen mode

이 구성은 기존 GitHub Actions 구조를 유지하면서 Stoplight 테스트 실행을 Apidog 테스트 실행으로 대체합니다.

Apidog 테스트 실행을 GitHub Actions에 통합하는 흐름은 Git 기반 API 워크플로 가이드에서도 다룹니다.

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

Stoplight Studio가 아니라 Stoplight Platform을 사용하던 팀이라면, 마이그레이션 전에 다음 항목을 대표 프로젝트로 검증하세요.

기능 Apidog 평가판에서 확인할 사항
비공개 문서 액세스 인증된 사용자 또는 특정 이메일 도메인으로 문서 접근을 제한할 수 있는지 확인합니다.
프로젝트 간 스키마/구성 요소 재사용 공유 components/schemas를 여러 프로젝트에서 참조할 수 있는지 실제 스키마 파일로 테스트합니다.
사용자 지정 린트 규칙 공유 여러 Apidog 프로젝트에서 공통 린트 프로필을 사용할 수 있는지 확인합니다. Spectral 규칙은 CI에서 별도 유지할 수 있습니다.
SSO/SCIM 프로비저닝 Apidog SSO가 현재 ID 공급자를 지원하는지, SCIM 프로비저닝 세분성이 사용자 수명 주기 관리에 맞는지 확인합니다.
감사 로그 어떤 이벤트가 어떤 형식으로 기록되는지 확인하고, 보안 및 컴플라이언스 요구 사항에 맞는지 검토합니다.

이 항목들은 장애물이 아니라 평가 과제입니다. 대부분은 2주 정도의 평가 기간 동안 대표 API 프로젝트로 검증할 수 있습니다.

FAQ

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

네. Spectral은 Apidog와 독립적으로 CI 파이프라인에서 계속 실행할 수 있습니다.

.spectral.yaml 파일은 리포지토리에 그대로 두고, GitHub Actions 또는 GitLab CI에서 PR마다 OpenAPI 파일을 린트하세요.

Apidog는 문서화, 목킹, 테스트를 처리하고 Spectral은 린팅을 처리합니다. 두 도구는 충돌하지 않습니다.

Spectral 설정은 Spectral 문서를 참고하세요.

리포지토리를 Apidog에 연결하면 $ref 경로가 깨집니까?

사양 파일의 상대 경로가 올바르면 깨지지 않습니다.

Apidog는 루트 OpenAPI 파일 위치를 기준으로 $ref를 해석합니다.

예를 들어 다음 참조가 있고:

$ref: ../models/error.json
Enter fullscreen mode Exit fullscreen mode

리포지토리 구조가 다음과 같다면 정상적으로 해석됩니다.

your-api-repo/
  reference/
    api.yaml
  models/
    error.json
Enter fullscreen mode Exit fullscreen mode

마이그레이션 초기에 외부 참조가 많은 사양 파일을 먼저 테스트하는 것이 좋습니다.

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

네. GitHub와 GitLab 모두 지원됩니다.

흐름은 동일합니다.

  1. GitHub 또는 GitLab 계정으로 인증합니다.
  2. 리포지토리를 선택합니다.
  3. 브랜치를 선택합니다.
  4. OpenAPI 사양 경로를 설정합니다.

브랜치 전략은 Git을 사용한 OpenAPI 버전 제어 가이드에서 더 자세히 확인할 수 있습니다.

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

Stoplight 구독을 취소하면 Stoplight 호스팅 문서 URL은 더 이상 작동하지 않습니다.

예:

docs.stoplight.io/your-org/your-api
Enter fullscreen mode Exit fullscreen mode

Apidog는 새 문서 URL을 제공합니다. 외부 서비스나 고객 문서에서 기존 Stoplight URL을 사용하고 있다면 DNS 또는 CDN 계층에서 리디렉션을 설정하세요.

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

아니요. 마이그레이션 중에는 삭제하지 않는 것이 좋습니다.

Apidog는 인식하지 못하는 파일을 무시합니다. 삭제하면 기존 Stoplight 사용자나 병렬 운영 중인 팀에 혼란을 줄 수 있습니다.

권장 순서는 다음과 같습니다.

  1. Apidog 연결 및 문서 검증
  2. 목 서버 검증
  3. 테스트 시나리오 재구성
  4. 팀 전환 완료
  5. 정리 PR에서 .stoplight.json, toc.json 제거 검토

결론

Stoplight에서 Apidog로 마이그레이션하는 것은 OpenAPI 프로젝트를 처음부터 다시 만드는 작업이 아닙니다.

OpenAPI 사양은 Git에 그대로 유지됩니다. 브랜치 워크플로도 유지됩니다. reference/, models/, docs/ 구조도 Apidog에서 사용할 수 있습니다.

실제 작업은 다음 세 가지입니다.

  1. .stoplight.json 및 toc.json 의존성을 Apidog 프로젝트 설정으로 대체합니다.
  2. Apidog Spec-First Mode로 GitHub 또는 GitLab 리포지토리를 연결합니다.
  3. Stoplight 테스트 시나리오를 Apidog 테스트 러너에서 다시 구성합니다.

기존 OpenAPI 리포지토리에 Apidog Spec-First Mode를 연결해 Stoplight 마이그레이션을 시작하세요. 사양 재업로드 없이, Git 기록과 브랜치 전략을 유지한 상태로 전환할 수 있습니다. Apidog를 다운로드하고 대표 API 프로젝트로 위 체크리스트를 검증해 보세요.

Top comments (0)