Rihpig

Posted on Jul 14 • Originally published at apidog.com

스탑라이트에서 API독으로 마이그레이션 가이드: 스펙 우선 모드에서 OpenAPI 스펙 관리

Stoplight에서 Apidog로 마이그레이션하는 작업은 OpenAPI 파일 하나를 가져오는 것으로 끝나지 않습니다. 실제로는 OpenAPI 계약, Markdown 문서, JSON Schema 모델, 이미지, 탐색 구조, 테스트 및 협업 방식을 포함한 파일 기반 API 워크플로우 전체를 전환하는 작업입니다.

지금 Apidog를 사용해 보세요

많은 Stoplight 프로젝트에는 엔드포인트 정의 외에도 다음 자산이 포함됩니다.

Git에서 관리하는 OpenAPI 사양
Markdown 문서
JSON Schema 모델
로컬 이미지
toc.json 기반 문서 탐색 구조
.stoplight.json 기반 경로 설정
Postman 또는 Bruno 요청 컬렉션
CI 테스트 및 게시 자동화

OpenAPI 파일만 가져오면 엔드포인트 목록은 유지할 수 있지만, 문서 구조·모델 참조·테스트·목(mock)·협업 흐름은 분리될 수 있습니다.

Apidog Spec-first Mode는 OpenAPI 파일을 진리의 원천(source of truth) 으로 유지하면서 문서, 목(mock), 테스트, 보고서, 권한 및 협업 워크플로우에 연결할 수 있도록 지원합니다.

운영 설정 단계는 Spec-first Mode 도움말 가이드를 참조하세요.

Stoplight 마이그레이션이 OpenAPI 가져오기 이상인 이유

OpenAPI 파일은 API 계약을 정의합니다. 하지만 일반적인 Stoplight 프로젝트는 계약 주변의 파일 구조와 문서 자산까지 함께 관리합니다.

일반적인 프로젝트 자산은 다음과 같습니다.

OpenAPI 또는 Swagger 파일 — 보통 reference 또는 구성된 디렉터리에 저장
Markdown 문서 — 보통 docs 디렉터리에 저장
JSON Schema 모델 — 보통 models 디렉터리에 저장
문서에서 참조하는 로컬 이미지
경로 구성을 위한 .stoplight.json
문서 그룹화와 순서 지정을 위한 toc.json
x-stoplight-id, x-stoplight.id 등의 Stoplight 식별자

OpenAPI 파일만 단독으로 가져오면 다음 문제가 발생할 수 있습니다.

Markdown 문서를 다시 구성해야 함
기존 문서 탐색 순서가 달라짐
모델과 문서 간 연결이 끊김
이미지 참조가 깨짐
테스트와 요청 예시가 별도 도구에 남음
Git의 사양 파일과 API 워크스페이스 간 불일치가 발생함

따라서 마이그레이션은 단일 사양 파일이 아니라 저장소 전체의 파일 트리에서 시작해야 합니다.

마이그레이션 모델: 이관, 검토, 재구축, 연결

먼저 실제 진리의 원천을 확인하세요.

Git의 OpenAPI 파일이 API 계약을 정의한다면 Spec-first 마이그레이션은 해당 파일에서 시작할 수 있습니다. 반대로 Postman 또는 Bruno 컬렉션이 실제 요청 흐름과 테스트를 주도한다면, 먼저 OpenAPI와 컬렉션 간의 불일치를 정리해야 합니다.

핵심은 모든 자산을 무조건 그대로 복제하는 것이 아닙니다. Stoplight 프로젝트에는 다른 워크스페이스와 일대일로 매핑되지 않는 제품별 동작이 있을 수 있습니다.

다음 네 가지 범주로 자산을 분류하세요.

범주	포함되는 항목	마이그레이션 방식
이관(Carry over)	OpenAPI 파일, 지원되는 `.stoplight.json` 경로 설정, 지원되는 `toc.json` 탐색 입력, Markdown, 참조 이미지, 지원되는 JSON Schema 모델	파일 기반 프로젝트 컨텍스트를 Spec-first Mode로 가져옵니다.
검토(Review)	Markdown 링크, 앵커, 이미지, TOC 그룹화, 스키마 이름, 외부 `$ref`, Stoplight ID, 렌더링 차이	마이그레이션 결과가 운영 가능한 상태인지 검증합니다.
재구축(Rebuild)	Postman/Bruno 요청 흐름, 환경, 수동 테스트, 목, CI 작업, 게시 규칙	OpenAPI 계약을 중심으로 새 워크플로우를 구성합니다.
연결(Connect)	문서, 목 API, 테스트, CI 보고서, 권한, 협업, 파트너 워크플로우	Apidog에서 계약을 API 수명 주기 전반에 연결합니다.

Stoplight 마이그레이션은 두 계층으로 나누어 생각하면 됩니다.

파일 계층

OpenAPI 사양, Markdown, 모델, 이미지, 프로젝트 구조 파일을 다룹니다. Spec-first Mode가 직접적으로 도움을 주는 영역입니다.
워크플로우 계층

API 변경 검토, 문서 게시, 테스트 실행, 목 관리, 보고서 공유, 권한 관리 및 팀 협업을 다룹니다.

파일을 가져오는 것만으로 워크플로우가 자동으로 이전되지는 않습니다. 마이그레이션 후에는 계약을 중심으로 워크플로우를 다시 연결해야 합니다.

Apidog Spec-first Mode가 Stoplight 프로젝트에 적합한 방식

Apidog Spec-first Mode는 파일 기반 API 워크플로우를 위한 방식입니다.

Git 연결 프로젝트에서는 저장소와 브랜치를 진리의 원천으로 유지할 수 있습니다.
파일 기반 프로젝트에서는 Git을 연결하기 전에 Apidog에서 사양 파일을 직접 작업할 수 있습니다.
사양(Specs) 워크스페이스에서 소스 파일, 파싱된 API 구조 및 편집 작업을 한곳에서 관리할 수 있습니다.

사양(Specs) 워크스페이스는 팀이 소스 파일, 파싱된 API 구조 및 편집 워크플로우를 한곳에서 관리할 수 있도록 합니다.

Stoplight 자산별 처리 방식

Stoplight 자산	Apidog에서 발생하는 일	검토할 사항
OpenAPI / Swagger 파일	API 모듈, 엔드포인트, 스키마 및 예시로 가져오고 동기화할 수 있습니다.	번들 참조, 변환 경고, 모듈 이름, 엔드포인트 그룹화를 확인합니다.
`.stoplight.json`	지원되는 필드를 사용해 OpenAPI, Markdown, JSON Schema 루트와 `tocPath`를 찾고 포함/제외 패턴을 적용할 수 있습니다.	전체 Stoplight 설정이 그대로 적용된다고 가정하지 마세요.
`toc.json`	지원되는 그룹과 구분 기호를 바탕으로 DOCS 폴더, Markdown 필터링·정렬, 제목, OAS/모듈 링크, 모델 가져오기를 지원할 수 있습니다.	최종 사이드바는 Apidog의 DOCS/OAS/MODELS 모델로 렌더링되므로 원래 Stoplight 탐색 구조와 다를 수 있습니다.
Markdown 문서	프로젝트 워크플로우로 이관할 수 있습니다.	내부 링크, 앵커, 서식, 누락 파일, 렌더링 결과를 확인합니다.
로컬 이미지	Markdown에서 참조하는 로컬 이미지는 지원되는 경우 가져올 수 있습니다.	깨진 참조, 외부 이미지, 데이터 URI, 미사용 이미지를 별도로 확인합니다.
JSON Schema 모델	`toc.json` 등 지원되는 구조에서 명시적으로 참조되는 파일은 모델로 이관할 수 있습니다.	스키마 형식, 이름, 폴더, 참조 관계를 확인합니다.
Stoplight ID	최상위 Stoplight ID는 반복 동기화 중 모듈 매칭에 도움이 될 수 있습니다.	엔드포인트 또는 페이지 수준 ID가 모두 보존된다고 가정하지 마세요.

`.stoplight.json` 및 `toc.json` 호환성 참고 사항

`.stoplight.json`

.stoplight.json은 동기화에 필요한 지원 범위의 경로 설정으로 취급하세요.

Apidog는 다음과 같은 항목을 사용할 수 있습니다.

OpenAPI 루트 디렉터리
Markdown 루트 디렉터리
JSON Schema 루트 디렉터리
OpenAPI 포함 패턴
전역 제외 패턴
tocPath

다만 모든 Stoplight formats 설정이나 프로젝트별 동작이 동일하게 적용된다고 가정하면 안 됩니다. 가져오기 결과를 직접 검증해야 합니다.

`toc.json`

toc.json은 다음과 같은 탐색 의미를 재구성하는 데 활용될 수 있습니다.

DOCS 폴더 생성
Markdown 문서 필터링 및 순서 지정
그룹 및 구분 기호
문서 제목
OAS 또는 모듈 링크
선택된 사양 항목 링크
TOC에서 참조한 JSON Schema 모델 가져오기

하지만 최종 문서 사이드바는 Apidog의 DOCS/OAS/MODELS 모델로 렌더링됩니다. 따라서 임의의 교차 유형 정렬이나 Stoplight 고유 레이아웃이 완전히 보존되지 않을 수 있습니다.

이미지와 JSON Schema

이미지는 Markdown에서 참조될 때 가장 예측 가능하게 이관됩니다.
참조되지 않은 이미지, 외부 이미지, 데이터 URI는 별도 검토가 필요합니다.
JSON Schema 파일은 단순히 특정 디렉터리에 있다는 이유만으로 자동 모델화된다고 가정하지 마세요.
toc.json 같은 지원 구조에서 명시적으로 참조하는 모델이 더 예측 가능한 대상입니다.

목표는 Stoplight를 픽셀 단위로 복제하는 것이 아닙니다. 목표는 이식 가능한 파일 기반 컨텍스트를 보존하고, 이를 문서·테스트·목·협업이 연결된 API 워크플로우로 확장하는 것입니다.

파일 가져오기에서 연결된 API 워크플로우로

기존 가져오기 방식에서는 OpenAPI 파일을 한 번 가져온 뒤 새 도구의 UI에서만 계속 수정하는 경우가 많습니다. 이 방식은 다음과 같은 불일치를 만들 수 있습니다.

Git의 OpenAPI 파일과 워크스페이스의 API 정의가 다름
문서가 사양 변경을 반영하지 않음
테스트가 이전 요청 컬렉션을 계속 사용함
팀마다 서로 다른 API 정의를 참조함

Spec-first Mode에서는 파일이 계속 기반이 됩니다.

Git 연결 Spec-first 프로젝트에서는 다음 흐름을 사용할 수 있습니다.

사양(Specs) 워크스페이스에서 파일을 편집합니다.
변경 사항을 검토합니다.
변경 사항을 커밋합니다.
저장소로 푸시합니다.
계약과 연결된 문서·테스트·목·보고서를 확인합니다.

파일 기반 프로젝트에서는 Git 연결 전에도 Apidog에서 사양 파일을 직접 편집하고 저장할 수 있습니다.

책임	권장 소스
API 계약	OpenAPI / Swagger 파일
프로젝트 파일 구조	저장소 또는 파일 기반 프로젝트 트리
지원되는 Stoplight 스타일 경로 설정	`.stoplight.json`
지원되는 문서 탐색 입력	`toc.json` 및 Markdown 문서
일일 API 협업	Apidog 프로젝트 워크스페이스
목, 테스트, 보고서, 팀 권한	Apidog 플랫폼 워크플로우

핵심은 데이터를 한 번 이동하는 것이 아니라, 계약 중심 워크플로우를 연결하는 것입니다.

Git 연결 방식 vs 파일 기반 마이그레이션 경로

모든 팀이 같은 수준의 Git 워크플로우를 사용하지는 않습니다.

경로	적합한 팀	일반적인 워크플로우
Git 연결 Spec-first 프로젝트	Git에서 OpenAPI 사양을 이미 관리하는 팀	저장소 연결 → 브랜치 동기화 → 파일 편집 → 커밋 → 푸시
파일 기반 Spec-first 프로젝트	Git 연결 전에 파일 기반 API 설계를 검증하려는 팀	Apidog에서 사양 파일 작업 → 변경 사항 저장 → 워크플로우 검증

대부분의 Stoplight 마이그레이션에서는 Git 연결 프로젝트가 장기적으로 더 명확한 모델입니다. 저장소를 계약의 진리의 원천으로 유지할 수 있기 때문입니다.

파일 기반 프로젝트는 다음 상황에서 유용합니다.

작성 경험을 먼저 평가하려는 경우
프로젝트 파일 구조를 정리 중인 경우
Git 기반 검토 프로세스를 도입하기 전인 경우
단계적으로 마이그레이션하려는 경우

마이그레이션 후 검토 체크리스트

프로젝트 파일을 가져올 수 있더라도 운영 전 검토는 필수입니다. 특히 문서가 많거나, 모델 파일이 많거나, 사용자 정의 탐색 구조를 사용한 프로젝트라면 더 중요합니다.

영역	확인할 사항
OpenAPI 모듈	의도한 모든 사양 파일이 가져와졌는지, 모듈 이름이 맞는지, 엔드포인트 그룹화가 올바른지 확인합니다.
외부 참조	`$ref` 종속성이 정상적으로 해결되는지, 변환 경고가 있는지 확인합니다.
린트 / 유효성 검사	가져온 OpenAPI 파일에 대해 Apidog 사양 유효성 검사를 실행합니다.
`.stoplight.json`	지원되는 루트 경로, 포함 패턴, 제외 패턴, `tocPath`가 예상대로 적용됐는지 확인합니다.
`toc.json`	그룹, 구분 기호, 제목, Markdown 순서, 링크, 모델 가져오기 및 최종 사이드바를 확인합니다.
Markdown 문서	제목, 서식, 상대 링크, 앵커, API 파일 및 작업 링크를 검토합니다.
이미지	로컬 참조 이미지가 렌더링되는지 확인하고 외부 이미지·데이터 URI·미사용 자산을 검토합니다.
모델	참조된 JSON Schema가 모델 리소스로 생성됐는지, 이름·폴더·참조가 맞는지 확인합니다.
Stoplight ID	반복 동기화에서 모듈 매칭이 기대대로 작동하는지 확인합니다.
테스트 및 목	기존 Postman, Bruno, CI 또는 별도 도구의 시나리오를 재구축하거나 연결합니다.
권한 및 게시	팀 접근 권한, 문서 공개 범위, 검토 규칙, 릴리스 책임을 새 워크스페이스에 맞게 설정합니다.

린트 및 유효성 검사

마이그레이션 후에는 가져온 OpenAPI 파일에 대해 사양 유효성 검사를 실행하세요.

Apidog는 Spectral 기반 편집기 유효성 검사를 위해 다음 파일을 사용할 수 있습니다.

.spectral.yaml
.spectral.yml
.spectral.json
.spectral.mjs

또한 .stoplight/styleguide.json을 대체 입력으로 사용할 수 있습니다.

단, 유효성 검사 성공은 모든 Stoplight 고유 동작이 보존됐다는 뜻이 아닙니다. 결과는 계약과 스타일 문제를 찾기 위한 검토 신호로 사용하세요.

Postman 및 Bruno 자산은 어떻게 처리해야 하나요?

많은 Stoplight 팀은 Postman 또는 Bruno도 함께 사용합니다. 이 자산은 OpenAPI 프로젝트 마이그레이션과 별도로 계획해야 합니다.

OpenAPI 파일: API 계약 정의
Postman 컬렉션: 요청 흐름, 예시, 환경, 테스트 정의
Bruno .bru 파일: Git 기반 요청 및 테스트 워크플로우 정의

마이그레이션 전 다음 질문에 답하세요.

질문	중요한 이유
OpenAPI가 진리의 원천인가, 컬렉션이 실제 API 동작을 주도하는가?	Spec-first 마이그레이션은 권위 있는 계약에서 시작해야 합니다.
어떤 요청 예시가 여전히 중요한가?	필요한 예시를 새 API 워크스페이스에서 재구축해야 합니다.
어떤 테스트가 계속 실행되어야 하는가?	테스트는 문서와 함께 자동 이전된다고 가정하면 안 됩니다.
어떤 환경과 비밀(secrets)을 공유하는가?	환경 관리는 사양 마이그레이션과 별도로 계획해야 합니다.
어떤 CI 작업이 기존 도구에 의존하는가?	유효성 검사, 테스트, 보고서 연결을 의도적으로 다시 구성해야 합니다.

Bruno 사용 팀은 Git 네이티브 워크플로우 자체의 가치를 유지할 수 있습니다. 다만 Bruno 자산은 팀의 사용 방식에 따라 별도 마이그레이션, 재구축 또는 교체가 필요할 수 있습니다.

권장 마이그레이션 계획

한 번에 모든 API 워크플로우를 옮기지 마세요. 먼저 계약을 옮기고, 이후 주변 워크플로우를 연결하는 단계적 접근이 안전합니다.

단계별 마이그레이션 계획: OpenAPI 계약을 먼저 이동한 다음 주변 워크플로우를 다시 연결합니다.

1. Stoplight 스타일 저장소 감사

다음 항목을 확인합니다.

OpenAPI 파일
.stoplight.json
toc.json
Markdown 문서
JSON Schema 모델
로컬 이미지
Postman 또는 Bruno 자산
CI 테스트 및 게시 스크립트

2. 진리의 원천 결정

Git의 OpenAPI 파일이 실제 계약 소스인지 확인하세요.

Postman이나 Bruno 컬렉션이 실질적인 API 동작을 주도한다면, 마이그레이션 전에 OpenAPI 정의와 컬렉션 간의 차이를 해결해야 합니다.

3. Spec-first 프로젝트 생성

다음 기준으로 경로를 선택하세요.

Git을 계약의 진리의 원천으로 유지할 준비가 됨 → Git 연결 프로젝트
파일 기반 편집 경험을 먼저 검증하고 싶음 → 파일 기반 프로젝트

4. 이관된 내용 검토

다음을 확인합니다.

OpenAPI 모듈
Markdown 문서
JSON Schema 모델
참조된 이미지
상대 링크와 앵커
지원되는 toc.json 탐색 입력
지원되는 .stoplight.json 경로 설정
사양(Specs) 유효성 검사 결과

가능하면 Apidog UI에서 증상을 수동으로 수정하기보다 원본 프로젝트 파일을 수정하세요.

5. 워크플로우 수준 자산 재구축

마이그레이션된 API 계약을 중심으로 다음을 다시 연결합니다.

목(mock)
API 테스트
요청 예시
CI 작업
보고서
팀 권한
문서 게시 책임

6. 새 워크플로우에서 실제 변경 사항 실행

작은 OpenAPI 변경 하나를 선택해 전체 흐름을 검증하세요.

예를 들면 다음과 같습니다.

paths:
  /users/{id}:
    get:
      summary: 사용자 조회

변경 후 다음을 확인합니다.

변경 사항이 사양 워크스페이스에 반영되는지
Git 브랜치 또는 파일 변경으로 저장되는지
문서가 업데이트되는지
관련 목과 테스트가 기대대로 동작하는지
CI 보고서와 팀 검토 흐름이 연결되는지

이 마이그레이션 경로가 적합한 경우

다음 조건에 해당한다면 이 경로가 적합합니다.

OpenAPI 또는 Swagger 사양을 파일로 관리함
Stoplight 프로젝트에 Markdown, 모델, 이미지, .stoplight.json, toc.json이 포함됨
API 검토 프로세스가 Git 브랜치 또는 풀 리퀘스트에 의존함
문서, 목, 테스트, 보고서, 협업이 계약과 계속 연결되기를 원함
API 파일과 프런트엔드, QA, 제품, 플랫폼, 파트너 팀의 워크스페이스 간 불일치를 줄이고 싶음

다음 상황에서는 추가 계획이 필요할 수 있습니다.

실제 진리의 원천이 OpenAPI가 아니라 Postman 또는 Bruno 컬렉션임
Stoplight의 사용자 정의 게시 동작에 크게 의존함
문서에 외부 링크, 앵커, 생성된 페이지, 미참조 자산이 많음
JSON Schema 모델이 수동 검토가 필요한 형식 또는 구조로 저장됨
Stoplight 탐색과 문서 렌더링을 픽셀 단위로 재현해야 함

자주 묻는 질문

Apidog Spec-first Mode는 Stoplight의 대안인가요?

OpenAPI 프로젝트를 파일 기반으로 유지하면서 문서, 테스트, 목(mock), 보고서, 권한 및 협업을 연결하려는 팀에게 Stoplight의 대안으로 사용할 수 있습니다.

OpenAPI 사양을 Git에 유지할 수 있나요?

네. Git 연결 Spec-first 프로젝트에서는 Git을 진리의 원천으로 유지하고, 브랜치를 동기화하며, 파일을 편집한 뒤 변경 사항을 저장소에 다시 커밋할 수 있습니다.

시작하려면 Git이 필요한가요?

아니요. 파일 기반 Spec-first 프로젝트에서 먼저 사양 파일을 작업한 뒤 필요할 때 Git을 연결할 수 있습니다.

`.stoplight.json`과 `toc.json`은 완전히 보존되나요?

아니요. Apidog는 지원되는 부분을 마이그레이션 입력으로 사용합니다.

.stoplight.json은 OpenAPI, Markdown, JSON Schema 루트, 포함 패턴, 전역 제외, tocPath 등의 경로 검색에 주로 활용됩니다.
toc.json은 DOCS 콘텐츠, OAS/모듈 링크, 선택 사양 항목 링크, TOC 참조 모델 가져오기에 활용될 수 있습니다.

최종 온라인 문서 사이드바는 Apidog의 DOCS/OAS/MODELS 모델에 의해 구성되므로, Stoplight의 정확한 탐색 구조와 임의의 교차 유형 순서는 보존되지 않을 수 있습니다.

Markdown 문서는 어떻게 되나요?

Markdown 문서는 Spec-first 프로젝트 워크플로우로 이관될 수 있습니다. toc.json에 포함된 문서는 지원되는 경우 더 많은 구조를 유지할 수 있습니다.

다만 내부 링크, 앵커, 이미지, 서식 및 렌더링은 반드시 검토해야 합니다.

JSON Schema 모델은 어떻게 되나요?

toc.json과 같은 지원되는 프로젝트 구조에서 명시적으로 참조된 JSON Schema 모델은 지원되는 경우 이관될 수 있습니다.

모델 디렉터리의 모든 JSON 파일이 자동으로 모델 리소스가 된다고 가정하지 마세요. 마이그레이션 후 형식, 이름, 폴더, 참조를 검토하세요.

이미지는 어떻게 되나요?

Markdown에서 참조하는 로컬 이미지는 지원되는 경우 가져올 수 있습니다.

formats.image.rootDir을 해당 디렉터리의 모든 이미지가 자동으로 이관된다는 보증으로 해석하면 안 됩니다. 외부 이미지, 데이터 URI, 깨진 참조, 미사용 이미지 파일은 별도 확인이 필요합니다.

마이그레이션 후 린트 또는 유효성 검사를 실행해야 하나요?

네. 가져온 OpenAPI 파일에 대해 사양(Specs) 유효성 검사를 실행하세요.

Apidog는 Spectral 기반 편집기 유효성 검사를 지원하며, 최상위 .spectral.yaml, .spectral.yml, .spectral.json, .spectral.mjs를 읽거나 .stoplight/styleguide.json을 대체 입력으로 사용할 수 있습니다.

결과는 계약 및 스타일 문제를 찾는 데 사용하세요. 유효성 검사 성공만으로 모든 Stoplight 고유 동작이 보존됐다고 판단하면 안 됩니다.

Bruno 또는 Postman 사용자는 어떻게 해야 하나요?

먼저 OpenAPI와 컬렉션 중 무엇이 진리의 원천인지 확인하세요.

Spec-first 마이그레이션은 OpenAPI와 관련 프로젝트 파일을 중심으로 진행됩니다. 컬렉션 기반 요청 흐름, 환경, 테스트는 별도의 마이그레이션 또는 재구축이 필요할 수 있습니다.

Apidog는 목, 테스트, CI/CD, 보고서, 협업도 지원하나요?

네. Spec-first Mode는 파일 기반 API 계약을 Apidog에 연결합니다. 더 넓은 Apidog 플랫폼은 문서, 목(mock), 테스트 시나리오, Apidog CLI를 활용한 CI/CD 실행, 보고서, 권한 및 팀 협업을 지원할 수 있습니다.

결론

Stoplight 마이그레이션은 파일 기반 API 작업을 포기하는 과정이어서는 안 됩니다.

저장소는 계속 진리의 원천으로 유지할 수 있습니다. OpenAPI 사양, Markdown 문서, 참조 이미지, TOC에서 참조하는 JSON Schema 모델, 지원되는 프로젝트 구조 파일도 이식하고 검토할 수 있습니다.

중요한 것은 파일만 옮기는 데 그치지 않는 것입니다. 마이그레이션 후에는 API 계약을 중심으로 문서, 목, 테스트, 보고서, 권한 및 협업을 다시 연결해야 합니다.

Stoplight 마이그레이션을 시작한다면 다음 순서를 따르세요.

저장소 구조를 감사합니다.
실제 API 계약의 진리의 원천을 결정합니다.
Spec-first 프로젝트를 생성합니다.
파일과 탐색 구조를 검토합니다.
테스트, 목, CI, 권한 및 게시 워크플로우를 재구축합니다.
작은 실제 변경으로 전체 흐름을 검증합니다.

엔터프라이즈 마이그레이션 계획은 Apidog Enterprise를 참조하세요.

DEV Community

스탑라이트에서 API독으로 마이그레이션 가이드: 스펙 우선 모드에서 OpenAPI 스펙 관리

Stoplight 마이그레이션이 OpenAPI 가져오기 이상인 이유

마이그레이션 모델: 이관, 검토, 재구축, 연결

Apidog Spec-first Mode가 Stoplight 프로젝트에 적합한 방식

Stoplight 자산별 처리 방식

`.stoplight.json` 및 `toc.json` 호환성 참고 사항

`.stoplight.json`

`toc.json`

이미지와 JSON Schema

파일 가져오기에서 연결된 API 워크플로우로

Git 연결 방식 vs 파일 기반 마이그레이션 경로

마이그레이션 후 검토 체크리스트

린트 및 유효성 검사

Postman 및 Bruno 자산은 어떻게 처리해야 하나요?

권장 마이그레이션 계획

1. Stoplight 스타일 저장소 감사

2. 진리의 원천 결정

3. Spec-first 프로젝트 생성

4. 이관된 내용 검토

5. 워크플로우 수준 자산 재구축

6. 새 워크플로우에서 실제 변경 사항 실행

이 마이그레이션 경로가 적합한 경우

자주 묻는 질문

Apidog Spec-first Mode는 Stoplight의 대안인가요?

OpenAPI 사양을 Git에 유지할 수 있나요?

시작하려면 Git이 필요한가요?

`.stoplight.json`과 `toc.json`은 완전히 보존되나요?

Markdown 문서는 어떻게 되나요?

JSON Schema 모델은 어떻게 되나요?

이미지는 어떻게 되나요?

마이그레이션 후 린트 또는 유효성 검사를 실행해야 하나요?

Bruno 또는 Postman 사용자는 어떻게 해야 하나요?

Apidog는 목, 테스트, CI/CD, 보고서, 협업도 지원하나요?

결론

Top comments (0)

Stoplight 마이그레이션이 OpenAPI 가져오기 이상인 이유

마이그레이션 모델: 이관, 검토, 재구축, 연결

Apidog Spec-first Mode가 Stoplight 프로젝트에 적합한 방식

Stoplight 자산별 처리 방식

.stoplight.json 및 toc.json 호환성 참고 사항

.stoplight.json

toc.json

이미지와 JSON Schema

파일 가져오기에서 연결된 API 워크플로우로

Git 연결 방식 vs 파일 기반 마이그레이션 경로

마이그레이션 후 검토 체크리스트

린트 및 유효성 검사

Postman 및 Bruno 자산은 어떻게 처리해야 하나요?

권장 마이그레이션 계획

1. Stoplight 스타일 저장소 감사

2. 진리의 원천 결정

3. Spec-first 프로젝트 생성

4. 이관된 내용 검토

5. 워크플로우 수준 자산 재구축

6. 새 워크플로우에서 실제 변경 사항 실행

이 마이그레이션 경로가 적합한 경우

자주 묻는 질문

Apidog Spec-first Mode는 Stoplight의 대안인가요?

OpenAPI 사양을 Git에 유지할 수 있나요?

시작하려면 Git이 필요한가요?

.stoplight.json과 toc.json은 완전히 보존되나요?

Markdown 문서는 어떻게 되나요?

JSON Schema 모델은 어떻게 되나요?

이미지는 어떻게 되나요?

마이그레이션 후 린트 또는 유효성 검사를 실행해야 하나요?

Bruno 또는 Postman 사용자는 어떻게 해야 하나요?

Apidog는 목, 테스트, CI/CD, 보고서, 협업도 지원하나요?

결론

`.stoplight.json` 및 `toc.json` 호환성 참고 사항

`.stoplight.json`

`toc.json`

`.stoplight.json`과 `toc.json`은 완전히 보존되나요?