Stoplight에서 Apidog로 마이그레이션하는 것은 단순히 OpenAPI 파일을 가져오는 것 이상입니다. 파일 기반 API 워크플로우를 전환하는 것을 의미합니다.
많은 팀에게 Stoplight 프로젝트는 엔드포인트 이상의 것을 포함했습니다. Git의 OpenAPI 사양, Markdown 문서, JSON Schema 모델, 로컬 이미지, 지원되는 toc.json 탐색 입력 및 지원되는 .stoplight.json 경로 설정 등이 있습니다.
팀은 Postman에 요청 예시가 있거나 CI에 테스트 스크립트가 있을 수도 있습니다. Stoplight에서 Apidog로 마이그레이션할 때 하나의 OpenAPI 파일만 가져오면 엔드포인트 목록은 유지될 수 있지만 워크플로우는 그렇지 않습니다.
Apidog Spec-first Mode는 Stoplight 마이그레이션 중에 팀이 OpenAPI 파일을 진리의 원천(source of truth)으로 유지하면서 해당 파일을 문서, 목(mock), 테스트, 보고서, 권한 및 협업을 위한 더 넓은 API 워크스페이스에 연결하는 데 도움을 줍니다.
이 가이드는 마이그레이션을 계획하는 방법을 설명합니다. 무엇을 이관할 수 있는지, 무엇을 검토해야 하는지, 무엇을 재구축해야 하는지, 그리고 OpenAPI 계약을 중심으로 무엇을 연결해야 하는지에 대한 내용입니다.
운영 설정 단계에 대해서는 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 파일만 가져오는 경우 엔드포인트는 이동할 수 있지만 프로젝트 모델은 여전히 손실될 수 있습니다. 문서를 재구축해야 할 수도 있습니다. 탐색이 이전 프로젝트와 일치하지 않을 수 있습니다. 모델이 문서에서 연결 해제될 수 있습니다. 테스트, 목(mock) 및 요청 예시는 여전히 별도의 도구에 남아 있을 수 있습니다.
더 나은 마이그레이션 계획은 단일 사양 파일이 아닌 저장소 또는 파일 트리에서 시작됩니다.
마이그레이션 모델: 이관, 검토, 재구축, 연결
시작하기 전에 실제 진리의 원천(source of truth)을 식별하십시오. Git의 OpenAPI 파일이 API 계약을 정의한다면, Spec-first 마이그레이션은 해당 파일에서 시작할 수 있습니다. Postman 또는 Bruno 컬렉션이 실제 요청 워크플로우를 주도하는 경우, 먼저 그 불일치를 해결하십시오.
가장 강력한 마이그레이션 계획은 "모든 것을 보존"하는 것이 아닙니다. Stoplight 프로젝트에는 다른 워크스페이스로 일대일 매핑되지 않는 제품별 동작이 포함될 수 있습니다.
대신 4단계 모델을 사용하십시오.
| 범주 | 포함되는 항목 | 마이그레이션 입장 |
|---|---|---|
| 이관 (Carry over) | OpenAPI 파일, 지원되는 .stoplight.json 경로 설정, 지원되는 toc.json 탐색 입력, Markdown 문서, 참조된 로컬 이미지, 지원되는 JSON Schema 모델. | 파일 기반 프로젝트 컨텍스트를 Spec-first Mode로 가져옵니다. |
| 검토 (Review) | Markdown 링크, 앵커, 이미지, TOC 그룹화, 스키마 이름 지정, 외부 $ref, Stoplight ID, 생성된 페이지 및 렌더링 차이. | 마이그레이션된 워크스페이스가 프로덕션 준비가 되었는지 확인합니다. |
| 재구축 (Rebuild) | 사양 프로젝트 외부에 있던 Postman 또는 Bruno 요청 흐름, 환경, 수동 테스트, 목(mock), CI 작업 및 게시 규칙. | OpenAPI 진리의 원천(source of truth)을 중심으로 이를 재구축합니다. |
| 연결 (Connect) | API 문서, 목(mock) API, 테스트, CI 보고서, 권한, 팀 협업 및 파트너 대면 워크플로우. | Apidog를 사용하여 API 수명 주기 전반에 걸쳐 계약을 유용하게 만듭니다. |
Stoplight 마이그레이션에는 두 가지 계층이 있기 때문에 이러한 구분이 중요합니다.
첫 번째 계층은 파일 계층입니다. OpenAPI 사양, Markdown 문서, 모델 파일, 이미지 및 프로젝트 구조 파일이 여기에 해당합니다. Spec-first Mode가 가장 직접적으로 유용한 부분입니다.
두 번째 계층은 워크플로우 계층입니다. 팀이 API 변경 사항을 검토하고, 문서를 게시하고, 테스트를 실행하고, 목(mock)을 관리하고, 보고서를 공유하고, 백엔드, 프런트엔드, QA, 제품 및 파트너 팀 간에 협업하는 방식입니다. 이 계층은 가져오기의 부산물로 취급되어서는 안 됩니다. Apidog가 계약을 나머지 API 수명 주기에 연결할 수 있는 부분입니다.
Apidog Spec-first Mode가 Stoplight 프로젝트에 어떻게 적합한가
Apidog의 Spec-first Mode는 파일 기반 워크플로우를 위해 구축되었습니다. 이는 Stoplight 프로젝트가 이미 사용하는 방식과 정확히 일치합니다.
Git 연결 프로젝트는 저장소를 중심에 둡니다. 브랜치는 진리의 원천(source of truth)으로 유지되며, Apidog는 브랜치와 동기화됩니다.
파일 기반 프로젝트를 사용하면 Apidog에서 사양 파일을 직접 작업할 수 있습니다. 준비가 되면 나중에 Git을 연결할 수 있습니다.
사양(Specs) 워크스페이스는 소스 파일을 관리하고, 파싱된 API 구조를 확인하며, 모든 편집 워크플로우를 처리할 수 있는 단일 공간을 제공합니다.
다음은 각 Stoplight 자산 유형이 Apidog에서 작동하는 방식입니다.
| Stoplight 자산 | Apidog에서 발생하는 일 | 검토 사항 |
|---|---|---|
| OpenAPI / Swagger 파일 | API 모듈, 엔드포인트, 스키마 및 예시로 가져오고 동기화할 수 있습니다. | 번들 참조, 변환 경고, 모듈 이름 지정 및 엔드포인트 그룹화를 검토합니다. |
.stoplight.json | 지원되는 필드는 Apidog가 OpenAPI, Markdown 및 JSON Schema 루트를 찾고, OpenAPI 포함 패턴을 적용하고, 전역 제외 패턴을 적용하며, tocPath를 해결하는 데 도움을 줄 수 있습니다. | 전체 Stoplight 프로젝트 구성이 아닌 동기화를 위한 경로 검색으로 취급하십시오. 모든 Stoplight formats 설정 또는 프로젝트 동작이 동일하게 적용된다고 가정하지 마십시오. |
toc.json | Apidog가 지원되는 그룹 및 구분 기호에서 DOCS 폴더를 생성하고, TOC 목록에 있는 Markdown 문서를 필터링하고 정렬하며, TOC 제목을 적용하고, DOCS 폴더를 가져온 OAS 모듈 또는 선택한 사양 항목에 연결하고, 지원되는 경우 TOC 참조 JSON Schema 모델을 가져오는 데 도움을 줄 수 있습니다. | 가져오기 후 최종 Apidog 사이드바를 검토하십시오. 최종 구조는 Apidog의 DOCS/OAS/MODELS 모델을 통해 렌더링되므로, 정확한 Stoplight 탐색 또는 임의의 교차 유형 순서 지정은 보존되지 않을 수 있습니다. |
| Markdown 문서 | Markdown 문서는 프로젝트 워크플로우로 이관될 수 있습니다. TOC 목록에 있는 문서는 지원되는 경우 더 많은 구조를 유지할 수 있습니다. | 내부 링크, 앵커, 서식, 누락된 파일 및 렌더링 차이를 검토합니다. |
| 로컬 이미지 | Markdown에서 참조하는 로컬 이미지는 지원되는 경우 가져올 수 있습니다. | 깨진 참조, 외부 이미지, 데이터 URI 및 문서에서 참조하지 않는 이미지를 검토합니다. 이미지 루트 설정을 자산 라이브러리 가져오기 보증으로 취급하지 마십시오. |
| JSON Schema 모델 | toc.json과 같은 지원되는 프로젝트 구조에서 명시적으로 참조하는 JSON Schema 파일은 지원되는 경우 모델로 이관될 수 있습니다. | 스키마 형식, 이름 지정, 그룹화, 참조 및 모든 모델을 가져와야 하는지 여부를 검토합니다. |
| Stoplight ID | 최상위 Stoplight ID는 Apidog가 동기화 전반에 걸쳐 가져온 모듈을 일치시키는 데 도움을 줄 수 있습니다. | 엔드포인트 수준 또는 페이지 수준의 ID가 완전히 보존된다고 가정하지 마십시오. |
Stoplight 프로젝트 파일에 대한 호환성 참고 사항
.stoplight.json은 동기화를 위한 지원되는 경로 구성 하위 집합으로 취급되어야 합니다. Apidog는 OpenAPI, Markdown 및 JSON Schema의 지원되는 루트 디렉터리, OpenAPI 포함 패턴, 전역 제외 패턴 및tocPath를 사용할 수 있습니다. 다른 Stoplight 프로젝트 설정은 확인되지 않는 한 무시되는 것으로 간주해야 합니다.toc.json은 Apidog에서 DOCS 폴더, Markdown 순서, OAS/모듈 링크, 선택된 사양 항목 링크 및 TOC 참조 모델 가져오기를 포함하여 지원되는 탐색 의미를 재구축하는 데 도움을 줄 수 있습니다. 최종 사이드바는 여전히 Apidog의 DOCS/OAS/MODELS 모델을 통해 렌더링되므로, 임의의 Stoplight 레이아웃 및 정확한 교차 유형 순서는 보존되지 않을 수 있습니다.toc.json은 최종 온라인 문서 사이드바를 완전히 사용자 정의하지 않습니다.- 이미지는 Markdown에서 참조될 때 주로 마이그레이션됩니다. 참조되지 않은 자산, 외부 이미지 및 데이터 URI는 별도로 검토해야 합니다.
- JSON Schema 파일은 디렉터리에서만 추정하는 것보다
toc.json과 같은 지원되는 프로젝트 구조에 의해 명시적으로 참조될 때 가장 예측 가능합니다.
이는 팀에게 실용적인 시작점을 제공합니다. 기존 프로젝트 파일을 사용하여 가능한 한 많은 API 워크스페이스를 재구축한 다음, Stoplight 특정 동작에 의존하는 부분을 검토합니다. 목표는 Stoplight를 픽셀 단위로 재현하는 것이 아니라, 이식 가능한 파일 기반 프로젝트 컨텍스트를 보존하고 이를 더 넓은 API 수명 주기에 다시 연결하는 것입니다.
파일 가져오기에서 연결된 API 워크플로우로
기존 가져오기 워크플로우에서 팀은 종종 OpenAPI 파일을 한 번 가져온 다음 새 도구에서 시각적으로 계속 작업합니다. 이는 불일치를 야기할 수 있습니다. Git의 파일, 문서 및 API 워크스페이스가 더 이상 동일한 진리의 원천(source of truth)을 나타내지 않을 수 있습니다.
Spec-first Mode는 다릅니다. 파일이 기반으로 유지됩니다.
Git 연결 Spec-first 프로젝트에서 팀은 사양(Specs) 워크스페이스에서 파일을 편집한 다음 변경 사항을 커밋하고 저장소로 푸시할 수 있습니다. 파일 기반 프로젝트에서는 팀이 Git을 연결하기 전에 Apidog 내에서 사양 파일을 편집하고 저장할 수 있습니다.
실질적인 구분은 다음과 같습니다.
| 책임 | 권장 소스 |
|---|---|
| API 계약 | OpenAPI / Swagger 파일 |
| 프로젝트 파일 구조 | 저장소 또는 파일 기반 프로젝트 트리 |
| 지원되는 Stoplight 스타일 경로 설정 | .stoplight.json |
| 지원되는 문서 탐색 입력 | toc.json 및 Markdown 문서 |
| 일일 API 협업 | Apidog 프로젝트 워크스페이스 |
| 목(mock), 테스트, 보고서 및 팀 권한 | 더 넓은 Apidog 플랫폼 워크플로우 |
이것이 핵심 마이그레이션 가치입니다. 팀은 파일 우선 계약 모델을 유지하면서 더 많은 이해관계자에게 해당 계약을 중심으로 유용한 API 워크스페이스를 제공할 수 있습니다.
그것은 데이터를 이동하는 것과 워크플로우를 이동하는 것의 차이입니다. 파일을 가져오는 것은 계약을 한 번 이동시키는 것입니다. Spec-first 프로젝트를 연결하는 것은 팀에게 계약을 중심으로 하는 워크스페이스를 제공합니다.
Git 연결 방식 vs 파일 기반 마이그레이션 경로
모든 Stoplight 팀이 동일한 워크플로우 성숙도에서 시작하는 것은 아닙니다.
일부 팀은 이미 Git 브랜치와 풀 리퀘스트를 통해 모든 API 변경 사항을 검토합니다. 다른 팀은 API 사양과 문서를 파일로 가지고 있지만, 외부 Git 제공업체를 첫 배포의 일부로 만들 준비가 되어 있지 않습니다.
Apidog Spec-first Mode는 두 가지 경로를 모두 지원합니다.
| 경로 | 가장 적합한 대상 | 일반적인 워크플로우 |
|---|---|---|
| Git 연결 Spec-first 프로젝트 | Git에서 OpenAPI 사양을 이미 관리하는 팀. | 저장소 연결, 브랜치 동기화, 파일 편집, 커밋 및 푸시. |
| 파일 기반 Spec-first 프로젝트 | Git 연결 전에 파일 기반 API 설계를 원하는 팀. | Apidog에서 사양 파일로 작업, 변경 사항 저장, 먼저 워크플로우 유효성 검사. |
대부분의 Stoplight 마이그레이션에서 Git 연결 프로젝트는 저장소가 계약의 진리의 원천(source of truth)으로 유지되므로 더 명확한 장기 모델입니다.
파일 기반 프로젝트는 팀이 작성 경험을 평가하거나, 프로젝트 파일을 정리하거나, 더 엄격한 Git 워크플로우를 채택하기 전에 마이그레이션을 준비하려는 경우에 유용합니다.
마이그레이션 후 검토해야 할 사항
프로젝트 파일이 이관될 수 있는 경우에도 마이그레이션에는 검토 과정이 포함되어야 합니다. 이는 특히 대규모 문서 사이트, 많은 스키마 파일 또는 사용자 정의된 Stoplight 탐색 기능을 가진 팀에게 중요합니다.
Spec-first 프로젝트를 생성한 후 이 체크리스트를 사용하십시오.
| 영역 | 확인할 사항 |
|---|---|
| OpenAPI 모듈 | 의도한 모든 사양 파일이 가져와졌는지, 모듈 이름이 올바른지, 엔드포인트가 예상대로 그룹화되었는지 확인합니다. |
| 외부 참조 | $ref 종속성이 예상대로 해결되었는지, 변환 문제가 보고되었는지 확인합니다. |
| 린트(Lint) / 유효성 검사 | 가져온 OpenAPI 파일에 대해 Apidog 사양 유효성 검사를 실행합니다. Apidog는 최상위 .spectral.yaml, .spectral.yml, .spectral.json, .spectral.mjs를 사용할 수 있으며, Spectral 기반 편집기 유효성 검사를 위해 .stoplight/styleguide.json으로 대체할 수 있습니다. 발견된 사항을 검토 신호로 취급하고, 전체 Stoplight 스타일 가이드 거버넌스 마이그레이션으로 간주하지 마십시오. |
.stoplight.json | 지원되는 OpenAPI, Markdown 및 JSON Schema 루트, OpenAPI 포함 패턴, 전역 제외 패턴 및 tocPath를 확인합니다. 모든 Stoplight 구성 필드가 적용되었다고 가정하기보다는 실제 가져오기 결과를 확인합니다. |
toc.json | 지원되는 그룹, 구분 기호, 제목, Markdown 필터링 및 순서 지정, 클릭 가능한 그룹, OAS/모듈 링크, 선택된 사양 항목 링크, TOC 참조 모델 가져오기 및 최종 Apidog 사이드바 출력을 검토합니다. |
| Markdown 문서 | 서식, 제목, 상대 링크, 앵커 및 API 파일 또는 작업에 대한 링크를 확인합니다. |
| 이미지 | 로컬 참조 이미지가 올바르게 렌더링되는지 확인합니다. 외부 이미지, 데이터 URI, 깨진 참조 및 사용되지 않는 자산은 별도로 검토합니다. |
| 모델 | toc.json에서 참조된 JSON Schema 파일 중 어떤 것이 모델 리소스가 되었는지, 이름, 폴더 및 참조가 올바른지 확인합니다. |
| Stoplight ID | 모듈 매칭이 반복된 동기화에서 예상대로 작동하는지 확인합니다. 모든 리소스 유형에 대해 ID에만 의존하지 마십시오. |
| 테스트 및 목(mock) | 이전에 Postman, Bruno, CI 또는 별도의 도구에서 유지 관리되던 시나리오를 재구축하거나 다시 연결합니다. |
| 권한 및 게시 | 새 워크스페이스에서 팀 액세스, 문서 가시성, 검토 규칙 및 릴리스 책임을 재설정합니다. |
이 검토는 임시방편이 아닙니다. 파일 이동과 전체 제품별 경험 이동 간의 일반적인 차이점입니다.
Postman 및 Bruno 자산은 어떻게 되나요?
많은 Stoplight 팀은 Postman 또는 Bruno도 사용합니다. 해당 자산은 OpenAPI 마이그레이션과 별도로 계획되어야 합니다.
OpenAPI 파일은 API 계약을 정의합니다. Postman 컬렉션 및 Bruno .bru 파일은 일반적으로 요청 워크플로우, 예시, 환경 또는 테스트를 정의합니다. 이들은 가치 있을 수 있지만, Stoplight 스타일 OpenAPI 프로젝트와 동일한 마이그레이션 대상은 아닙니다.
마이그레이션 전에 다음 질문에 답하십시오.
| 질문 | 중요한 이유 |
|---|---|
| OpenAPI가 진리의 원천(source of truth)인가, 아니면 컬렉션이 실제 API 동작을 주도하는가? | Spec-first 마이그레이션은 권위 있는 계약에서 시작해야 합니다. |
| 어떤 요청 예시가 여전히 중요한가? | 연결된 API 워크스페이스를 중심으로 중요한 예시를 재구축합니다. |
| 어떤 테스트가 계속 실행되어야 하는가? | 문서와 함께 마이그레이션된다고 가정하지 말고 API 테스트를 새 워크플로우로 이동하거나 다시 연결합니다. |
| 어떤 환경 및 비밀(secrets)이 공유되는가? | 사양 마이그레이션과 별도로 환경 관리를 계획합니다. |
| 어떤 CI 작업이 현재 도구에 의존하는가? | 유효성 검사, 테스트 및 보고서 연결을 의도적으로 다시 수행합니다. |
Bruno 사용자에게 핵심 통찰력은 Git 네이티브 워크플로우가 이미 가치가 있다는 것입니다. Spec-first Mode는 계약을 파일 기반으로 유지할 수 있지만, Bruno 자산은 팀이 사용하는 방식에 따라 별도의 마이그레이션, 재구축 또는 교체가 필요할 수 있습니다.
권장 마이그레이션 계획
모든 API 워크플로우를 한 번에 이동하려고 하는 대신 단계별 계획을 사용하십시오.
단계별 마이그레이션 계획: OpenAPI 계약을 먼저 이동한 다음 주변 워크플로우를 다시 연결합니다.
1. Stoplight 스타일 저장소 감사
OpenAPI 파일, .stoplight.json, toc.json, Markdown 문서, 모델, 이미지 및 관련 요청 또는 테스트 자산을 식별합니다.
2. 진리의 원천(source of truth) 결정
Git의 OpenAPI 파일이 계약 소스인지 확인합니다. 다른 도구나 컬렉션이 효과적인 진리의 원천이라면, 마이그레이션 전에 이를 해결하십시오.
3. Spec-first 프로젝트 생성
팀이 Git을 진리의 원천(source of truth)으로 유지할 준비가 되었다면 Git 연결 프로젝트를 선택하십시오. 팀이 파일 워크플로우를 먼저 검증하고 싶다면 파일 기반 프로젝트를 선택하십시오.
4. 이관된 내용 검토
모듈, 문서, 모델, 참조된 이미지, 링크, 지원되는 toc.json 탐색 입력, 지원되는 .stoplight.json 경로 설정 및 사양(Specs) 유효성 검사 결과를 확인합니다. 증상을 수동으로 패치하는 대신 가능한 경우 프로젝트 파일을 수정하십시오.
5. 워크플로우 수준 자산 재구축
마이그레이션된 API 계약을 중심으로 목(mock), 테스트, 요청 예시, CI 작업, 보고서, 권한 및 게시 책임을 다시 연결합니다.
6. 새 워크플로우를 통해 첫 실제 변경 사항 실행
작은 OpenAPI 변경을 수행하고, 이를 검토하고, 동기화하고, 필요한 경우 문서를 업데이트하고, 다운스트림 목(mock), 테스트 및 보고서가 예상대로 작동하는지 확인합니다.
팀이 이미 Stoplight 스타일 저장소에서 OpenAPI 파일, Markdown 문서 및 스키마 모델을 유지 관리하고 있다면, Apidog Spec-first Mode는 전체 워크플로우를 재구축하기 전에 마이그레이션 경로를 테스트하는 데 도움을 줄 수 있습니다.
이 마이그레이션 경로가 가장 적합한 경우
이 마이그레이션 경로는 다음 경우에 적합합니다.
- 팀이 OpenAPI 또는 Swagger 사양을 파일로 관리하는 경우;
- Stoplight 프로젝트에 Markdown 문서, 모델, 이미지,
.stoplight.json또는toc.json이 포함된 경우; - API 검토 프로세스가 이미 Git 브랜치 또는 풀 리퀘스트에 의존하는 경우;
- API 문서, 목(mock), 테스트, 보고서 및 협업이 계약과 계속 연결되기를 원하는 경우;
- API 파일과 프런트엔드, QA, 제품, 플랫폼 또는 파트너 팀이 사용하는 워크스페이스 간의 불일치를 줄이고 싶은 경우.
다음 경우에 더 많은 계획이 필요할 수 있습니다.
- 실제 API 진리의 원천(source of truth)이 OpenAPI가 아닌 Postman 또는 Bruno 컬렉션인 경우;
- Stoplight 프로젝트가 사용자 정의 게시 동작에 크게 의존하는 경우;
- 문서에 많은 외부 링크, 앵커, 생성된 페이지 또는 참조되지 않은 자산이 포함된 경우;
- JSON Schema 모델이 수동 검토가 필요한 형식 또는 구조로 저장된 경우;
- 팀이 Stoplight 탐색 또는 문서 렌더링을 픽셀 단위로 완벽하게 재현하기를 원하는 경우.
자주 묻는 질문
Apidog Spec-first Mode는 Stoplight의 대안인가요?
OpenAPI 프로젝트를 파일 기반으로 유지하면서 해당 파일을 중심으로 더 넓은 API 협업, 테스트, 목(mock), 문서화, 보고 및 권한 관리를 추가하려는 팀에게 Stoplight의 대안으로 사용될 수 있습니다.
OpenAPI 사양을 Git에 유지할 수 있나요?
네, 가능합니다. Git 연결 Spec-first 프로젝트에서 팀은 Git을 진리의 원천(source of truth)으로 유지하고, 브랜치를 동기화하며, 파일을 편집하고, 변경 사항을 저장소로 다시 커밋할 수 있습니다.
시작하려면 Git이 필요한가요?
아니요. 팀이 사양 파일로 먼저 작업한 다음 나중에 Git을 연결하려는 경우 파일 기반 Spec-first 프로젝트를 사용할 수 있습니다.
.stoplight.json과 toc.json은 완전히 보존되나요?
아니요. Apidog는 이 파일들의 지원되는 부분을 마이그레이션 입력으로 사용합니다. .stoplight.json은 주로 지원되는 OpenAPI, Markdown, JSON Schema 루트, OpenAPI 포함 패턴, 전역 제외 및 tocPath를 포함한 동기화 중 경로 검색에 사용됩니다. toc.json은 지원되는 DOCS 콘텐츠, OAS/모듈 링크, 선택된 사양 항목 링크 및 TOC 참조 모델 가져오기를 구성하는 데 도움을 줄 수 있습니다. 최종 온라인 문서 사이드바는 여전히 Apidog의 DOCS/OAS/MODELS 모델에 의해 제약되므로, 정확한 Stoplight 탐색 및 임의의 교차 유형 순서는 보존되지 않을 수 있습니다.
Markdown 문서는 어떻게 되나요?
Markdown 문서는 Spec-first 프로젝트 워크플로우로 이관될 수 있습니다. toc.json이 있는 경우, TOC 목록에 있는 문서는 지원되는 경우 더 많은 구조를 유지할 수 있습니다. 내부 링크, 앵커, 이미지 및 렌더링은 여전히 검토되어야 합니다.
JSON Schema 모델은 어떻게 되나요?
JSON Schema 모델은 toc.json과 같은 지원되는 프로젝트 구조에 의해 명시적으로 참조될 때 지원되는 경우 이관될 수 있습니다. 모델 디렉터리 아래의 모든 JSON 파일이 자동으로 모델 리소스가 된다고 가정하지 마십시오. 마이그레이션 후 스키마 형식, 이름, 폴더 및 참조를 검토하십시오.
이미지는 어떻게 되나요?
Markdown에서 참조하는 로컬 이미지는 지원되는 경우 가져올 수 있습니다. formats.image.rootDir을 해당 디렉터리의 모든 이미지 파일이 가져와질 것이라는 보증으로 취급하지 마십시오. 외부 이미지, 데이터 URI, 깨진 참조 및 사용되지 않는 이미지 파일은 별도로 확인해야 합니다.
마이그레이션 후 린트(lint) 또는 유효성 검사를 실행해야 하나요?
네. 마이그레이션 후 가져온 OpenAPI 파일에 대해 사양(Specs) 유효성 검사를 실행하십시오. Apidog는 Spectral 기반 편집기 유효성 검사를 지원하며 최상위 .spectral.yaml, .spectral.yml, .spectral.json, .spectral.mjs를 읽거나 .stoplight/styleguide.json으로 대체할 수 있습니다. 결과를 사용하여 계약 및 스타일 문제를 검토하십시오. 유효성 검사 성공을 모든 Stoplight 특정 동작이 보존되었다는 증거로 간주하지 마십시오.
Bruno 또는 Postman 사용자는 어떻게 해야 하나요?
먼저 OpenAPI 또는 컬렉션 중 어느 것이 진리의 원천(source of truth)인지 식별하십시오. Spec-first 마이그레이션은 OpenAPI 및 관련 프로젝트 파일을 중심으로 합니다. 컬렉션 기반 요청 워크플로우, 환경 및 테스트는 별도의 마이그레이션 또는 재구축이 필요할 수 있습니다.
Apidog는 목(mock), 테스트, CI/CD, 보고서 및 협업도 지원하나요?
네. Spec-first Mode는 파일 기반 API 계약을 Apidog에 연결하며, 더 넓은 Apidog 플랫폼은 해당 계약을 중심으로 문서, 목(mock), 테스트 시나리오, Apidog CLI를 사용한 CI/CD 실행, 보고서, 권한 및 팀 협업을 지원할 수 있습니다.
결론
Stoplight 마이그레이션이 파일 기반 API 작업을 포기하는 것을 의미해서는 안 됩니다.
저장소는 진리의 원천(source of truth)으로 유지될 수 있습니다. OpenAPI 사양, Markdown 문서, 참조된 이미지, TOC 참조 JSON Schema 모델 및 지원되는 프로젝트 구조 파일은 이식 가능하며 검토 가능하게 유지될 수 있습니다. 동시에 해당 파일을 중심으로 하는 API 워크플로우는 더 많이 연결될 수 있습니다.
Apidog Spec-first Mode는 Stoplight 팀에게 실용적인 마이그레이션 경로를 제공합니다. 지원되는 프로젝트의 파일 기반 부분을 이관하고, Stoplight 특정 구조를 신중하게 검토하며, 연결된 API 워크스페이스를 중심으로 워크플로우 수준 자산을 재구축하는 것입니다.
팀이 Stoplight 마이그레이션을 평가하고 있다면, 저장소 구조를 감사하고 어떤 파일이 API 계약을 정의하는지 결정하는 것부터 시작하십시오. 그런 다음 Spec-first Mode를 사용하여 해당 파일을 Apidog의 문서, 목(mock), 테스트, 보고서, 권한 및 협업에 연결하십시오.
엔터프라이즈 마이그레이션 계획에 대해서는 Apidog Enterprise를 참조하십시오.