Spec-first 모드(Beta)

Spec-first 모드는 API 사양 파일을 신뢰할 수 있는 단일 출처로 사용하려는 팀을 위한 모드입니다. 이 모드에서는 Apidog에서 OpenAPI 또는 Swagger 파일을 직접 설계하고 유지 관리하며, 편집하는 동안 생성된 API 문서를 미리 보고, 파일을 Git과 동기화할 수 있습니다.

팀이 이미 YAML 또는 JSON 사양 파일로 작업하거나, Git을 통해 API 변경 사항을 검토하거나, API 설계가 코드 저장소 워크플로에 자연스럽게 맞기를 원하는 경우 Spec-first 모드를 사용하십시오.

Spec-first 모드 작동 방식

일반 Apidog 프로젝트에서는 일반적으로 시각적 양식을 통해 API를 생성하고 편집합니다. Spec-first 프로젝트에서는 파일 기반 작업 공간이 기본 작업 공간입니다.

다음과 같은 파일로 작업합니다.

openapi.yaml

openapi.json

Swagger 2.0 파일

Markdown 파일 및 기타 지원 프로젝트 파일

Apidog는 사양 파일을 구문 분석하여 탐색 가능한 API 구조로 변환합니다. 원본 파일을 편집하고, 지원되는 시각적 양식을 사용하고, 사양을 검증하고, 생성된 문서를 미리 보고, 변경 사항을 Git에 다시 푸시할 수 있습니다.

Spec-first 프로젝트 생성

+ New Project를 클릭하십시오.

프로젝트 유형 선택기에서 Spec-first Mode를 선택하십시오.

GitHub, GitLab, Azure DevOps 또는 Bitbucket과 같은 Git 제공자를 연결하십시오.

조직 또는 작업 공간을 선택한 다음, 기존 저장소를 선택하거나 옵션을 사용할 수 있는 경우 새 저장소를 생성하십시오.

Apidog가 동기화할 기본 브랜치를 선택하십시오.

웹훅을 설치할지 선택하십시오.

웹훅을 설치하면 Git 저장소의 푸시가 자동 동기화를 트리거할 수 있습니다. 일반적으로 저장소에 대한 관리자 권한이 필요합니다. 관리자 권한이 없는 경우 웹훅 설치를 건너뛰고 수동으로 동기화할 수 있습니다.

프로젝트 이름을 입력하고, 멤버 권한을 구성한 다음 Create를 클릭하십시오.

생성 후 Apidog는 첫 번째 동기화를 수행합니다. 저장소의 기본 브랜치가 main이 아닌 경우 Apidog는 저장소 브랜치 이름을 프로젝트 기본 브랜치로 사용합니다.

Spec-first 프로젝트에는 샘플 프로젝트 데이터가 포함되지 않습니다. API 콘텐츠는 사양 파일에서 가져옵니다.

Specs 작업 공간

Spec-first 프로젝트에는 왼쪽 사이드바에 Specs 작업 공간이 포함됩니다. 이곳은 사양 파일 및 Git 동기화를 관리하는 기본 위치입니다.

작업 공간에는 세 가지 주요 영역이 포함됩니다.

파일 탐색기: 동기화된 저장소의 파일 및 폴더를 찾아보고 관리합니다.

API 구조 트리: 개요, 엔드포인트, 스키마 및 정의와 같은 구문 분석된 OpenAPI 콘텐츠를 탐색합니다.

편집기: 코드 보기에서 파일을 편집하거나, 지원되는 OpenAPI 노드의 경우 양식 보기에서 편집합니다.

구조 트리에서 엔드포인트, 스키마 또는 기타 지원되는 노드를 선택하면 Apidog가 소스 파일의 관련 부분을 엽니다. 이를 통해 Specs 작업 공간을 벗어나지 않고 파일 수준 보기와 API 수준 보기 사이를 이동할 수 있습니다.

사양 파일 편집

편집기는 다양한 파일 유형과 편집 모드를 지원합니다.

코드 보기

YAML, JSON, Markdown 및 기타 텍스트 파일을 직접 편집하려면 Code 보기를 사용하십시오. 이는 Spec-first 모드에서 작업하는 기본 방식입니다.

양식 보기

지원되는 OpenAPI 노드의 경우 Apidog는 Form 보기도 제공합니다. 이를 통해 기본 사양 파일을 신뢰할 수 있는 단일 출처로 유지하면서, 구조화된 컨트롤을 통해 일반적인 API 필드를 편집할 수 있습니다.

양식 보기는 다음과 같은 지원되는 노드에서 사용할 수 있습니다.

API 개요

엔드포인트

스키마

정의

선택한 파일 또는 노드를 양식 보기에서 편집할 수 없는 경우 Apidog는 코드 보기를 유지합니다.

편집 중 검증 및 미리 보기

Spec-first 모드에는 편집기 헤더에 검증 및 미리 보기 도구가 포함됩니다.

검증

Validation 패널에는 경고 및 오류를 포함하여 현재 사양에서 감지된 문제가 표시됩니다. 검증 배지는 감지된 문제의 총 개수를 표시합니다.

변경 사항을 커밋하기 전에 이 패널을 사용하여 구문 문제, 누락된 필수 필드 및 규칙 위반을 찾으십시오.

미리 보기

Preview 패널에는 선택한 사양 노드가 생성된 API 문서에서 어떻게 표시되는지 보여 줍니다.

미리 보기는 다음 항목에 사용할 수 있습니다.

API 개요

엔드포인트

스키마

정의

엔드포인트의 경우 Preview에는 다음이 포함됩니다.

Docs: 생성된 엔드포인트 문서입니다.

Try it out: 선택한 엔드포인트 정의를 기반으로 요청을 보내기 위한 요청 패널입니다.

스키마, 정의 및 개요 노드의 경우 Preview에는 생성된 문서 보기가 표시됩니다.

Validation과 Preview는 동일한 사이드 패널을 사용합니다. 하나를 열면 다른 하나가 닫힙니다.

Git에서 변경 사항 동기화

다른 팀 멤버가 연결된 저장소에 변경 사항을 푸시하면, 최신 파일을 Apidog로 가져올 수 있습니다.

Specs 작업 공간을 여십시오.

Specs 사이드바에서 현재 브랜치 이름을 클릭하십시오.

Git Pull을 클릭하십시오.

웹훅 동기화가 설치되어 있는 경우 Apidog는 Git 제공자로부터 푸시 이벤트를 수신하고 자동으로 동기화를 트리거할 수도 있습니다.

변경 사항을 Git에 커밋 및 푸시

Apidog에서 파일을 편집한 후 변경 사항을 연결된 저장소에 다시 푸시하십시오.

Specs 작업 공간에서 하나 이상의 파일을 편집하십시오.

수정, 추가, 이름 변경 및 삭제된 파일을 검토하려면 Changes를 클릭하십시오.

Commit & Push를 클릭하십시오.

Push to Git repo 모달에서 포함할 파일을 선택하십시오.

커밋 메시지를 입력하십시오.

Push를 클릭하십시오.

로컬 편집 내용을 유지하지 않으려면 푸시하기 전에 Discard all changes를 사용하십시오.

브랜치 관리

Spec-first 모드는 브랜치 기반 협업을 지원합니다. Apidog는 동기화된 Git 브랜치를 프로젝트 브랜치에 매핑하므로 사양의 버전 간 전환할 수 있습니다.

브랜치 전환

Specs 사이드바에서 브랜치 이름을 클릭하고 드롭다운에서 다른 브랜치를 선택하십시오.

기존 Git 브랜치 추적

Git에 브랜치가 있지만 Apidog로 가져오지 않은 경우 Import New Branch를 클릭하고 브랜치를 선택한 다음 가져오십시오. 그러면 Apidog가 해당 브랜치 추적 및 동기화를 시작합니다.

브랜치 생성

Project Settings > Git & Branches를 열고 New Branch를 클릭하여 기존 프로젝트 브랜치에서 브랜치를 생성하십시오.

브랜치 다시 동기화

브랜치 동기화가 실패하거나 파일이 오래된 것처럼 보이면 Project Settings > Git & Branches에서 Re-sync를 사용하십시오. 이렇게 하면 해당 브랜치의 동기화 상태가 재설정되고 파일을 다시 가져옵니다.

동기화 로그 보기

동기화가 실패하면 브랜치 작업을 열고 View Logs를 선택하여 동기화 세부 정보를 검사하십시오.

브랜치 추적 중지 또는 삭제

추적 중인 브랜치를 삭제하면 Apidog의 동기화 구성에서 해당 브랜치가 제거됩니다. 기본 브랜치가 아닌 경우 프로젝트 브랜치 레코드도 제거할 수 있습니다.

웹훅 동기화 및 권한

웹훅 동기화는 선택 사항이지만, 저장소 푸시에 맞춰 Apidog를 최신 상태로 유지하려는 팀에는 권장됩니다.

웹훅 동기화가 활성화된 경우:

Apidog가 연결된 Git 제공자에 웹훅을 등록합니다.

지원되는 푸시 이벤트만 처리됩니다.

Apidog는 동기화 전에 웹훅 서명 또는 토큰을 확인합니다.

권한 요구 사항:

웹훅을 설치하려면 일반적으로 저장소 관리자 권한이 필요합니다.

변경 사항을 푸시하려면 쓰기 권한이 필요합니다.

웹훅 설치를 건너뛰어도 수동 동기화는 계속 사용할 수 있습니다.

프로젝트 생성 중 웹훅 설치를 건너뛴 경우, 나중에 Project Settings > Git & Branches에서 설치할 수 있습니다.

스토리지 기반 Spec-first 프로젝트

일부 Spec-first 프로젝트는 외부 Git 저장소 대신 Apidog의 내부 스토리지를 사용할 수 있습니다.

이러한 프로젝트도 Specs 작업 공간, 파일 기반 편집, 검증, 미리 보기 및 브랜치 관리를 계속 사용합니다.

UI 레이블은 약간 다릅니다.

Git Pull은 Sync로 표시됩니다.

Commit & Push는 Save로 표시됩니다.

Git 제공자 정보 및 외부 웹훅 설정은 숨겨집니다.

참고 사항 및 제한 사항

Spec-first 모드는 현재 베타입니다.

Specs 작업 공간은 Spec-first 프로젝트에만 표시됩니다.

Spec-first 프로젝트는 샘플 API 데이터를 생성하지 않습니다.

사양 파일은 신뢰할 수 있는 단일 출처입니다. 변경 사항은 Specs 작업 공간을 통해 수행하거나 Git을 통해 동기화해야 합니다.

충분한 저장소 권한이 없는 경우 웹훅 설치가 실패할 수 있습니다. 쓰기 권한이 있는 경우에도 수동 동기화를 사용할 수 있습니다.

Spec-first 모드(Beta)

Spec-first 모드 작동 방식#

Spec-first 프로젝트 생성#

Specs 작업 공간#

사양 파일 편집#

코드 보기#

양식 보기#

편집 중 검증 및 미리 보기#

검증#

미리 보기#

Git에서 변경 사항 동기화#

변경 사항을 Git에 커밋 및 푸시#

브랜치 관리#

브랜치 전환#

기존 Git 브랜치 추적#

브랜치 생성#

브랜치 다시 동기화#

동기화 로그 보기#

브랜치 추적 중지 또는 삭제#

웹훅 동기화 및 권한#

스토리지 기반 Spec-first 프로젝트#

참고 사항 및 제한 사항#