Apidog 스펙 우선 모드(Spec-First Mode)는 OpenAPI 스펙을 소스 코드로 취급하는 팀을 위해 구축된 베타 작업 공간입니다. IDE 스타일 편집기에서 YAML 또는 JSON으로 스펙을 직접 작성한 다음, 연결된 Git 저장소와 양방향으로 동기화합니다. 파일과 사용자 사이에 폼 기반 편집기가 없습니다. 스펙 *자체*가 프로젝트입니다. API 도구를 벗어나지 않고 실제 코드 편집기에서 openapi.yaml을 편집하고 GitHub에 푸시하고 싶었다면, 이 모드가 바로 당신을 위한 것입니다.
이 가이드는 이 기능 자체에 대한 완전한 참조서입니다. 모든 기능, 전체 설정 가이드, 대상 사용자, 베타 버전에서 예상되는 제한 사항, 그리고 실용적인 FAQ를 다룹니다. 이 접근 방식의 광범위한 아이디어는 저희 Git-네이티브 API 워크플로우를 참조하십시오.
Apidog 스펙 우선 모드(Spec-First Mode)란 무엇인가요?
스펙 우선 모드(Spec-First Mode)는 API 디자인이 원시 OpenAPI 문서로 존재하는 Apidog의 베타 편집 모드입니다. 파일을 열고 YAML 또는 JSON을 편집하고, 유효성을 검사하고, 커밋하고, Git에 푸시합니다. Apidog는 스펙과 저장소를 양방향으로 동기화합니다. 팀원의 변경 사항을 풀(pull)하면 편집기가 업데이트되고, 편집 내용을 푸시(push)하면 저장소가 업데이트됩니다.
이 모드는 특히 한 종류의 팀을 위해 구축되었습니다: 이미 네이티브 Git 워크플로우를 운영하는 사람들입니다. 풀 리퀘스트에서 계약 버전을 관리하는 백엔드 엔지니어, 플랫폼 팀, API 우선 기업들은 이 모드에 편안함을 느낄 것입니다. 스펙 파일은 단일 진실 공급원이 되며, Git은 나머지 코드베이스에서 하는 것처럼 히스토리, 검토 및 브랜칭을 처리합니다.
이는 대부분의 API 도구가 작동하는 방식과 다릅니다. 대부분의 도구는 그래픽 폼 뒤에 스펙을 숨깁니다. 스펙 우선 모드는 파일을 직접 보여줍니다.
스펙 우선 모드(Spec-First Mode)와 디자인 우선 모드(Design-First Mode) 비교
Apidog는 두 가지 모드를 제공합니다. 디자인 우선 모드(Design-First Mode)는 대부분의 팀이 시작하는 시각적 폼 기반 편집기입니다. 스펙 우선 모드(Spec-First Mode)는 이 가이드에서 다루는 코드 편집기 접근 방식입니다. 간략한 내용은 다음과 같습니다. 장단점에 대한 자세한 내용은 저희 스펙 우선 대 디자인 우선 비교를 참조하십시오.
| 측면 | 디자인 우선 모드 | 스펙 우선 모드 (베타) |
|---|---|---|
| 주요 편집기 | 시각적 폼 및 UI 패널 | 원시 YAML/JSON 코드 편집기 |
| 진실 공급원 | Apidog 프로젝트 데이터베이스 | Git 저장소의 스펙 파일 |
| Git 동기화 | 내보내기/가져오기 기반 | 네이티브 양방향 동기화 |
| 적합 대상 | 시각 디자이너, 혼합 팀 | Git 네이티브 엔지니어링 팀 |
| 학습 곡선 | 부드럽고 안내됨 | OpenAPI를 안다면 익숙함 |
어떤 모드도 "더 좋다"고 할 수 없습니다. 이들은 서로 다른 팀에 적합합니다. 아래에서 다루겠지만, 두 모드 사이를 전환할 수 있습니다.
주요 기능
스펙 우선 모드는 단순한 텍스트 상자 이상입니다. 편집기, 네비게이터, Git 통합 및 팀 제어 기능을 포함합니다. 다음은 각 기능에 대한 자세한 설명입니다.
IDE 스타일 OpenAPI 편집기
작업 공간의 중심에는 OpenAPI 문서를 위한 완전한 코드 편집기가 있습니다. 원시 YAML 또는 JSON을 직접 편집합니다. 매일 사용하는 편집기처럼 작동합니다.
키, 값, 구조에 색상을 입혀 파일이 대규모에서도 가독성을 유지하는 구문 강조 표시 기능을 제공합니다. 입력하는 동안 OpenAPI 사양에 대한 오류를 표시하는 스키마 유효성 검사 기능을 제공하여, 잘못된 응답 객체나 누락된 필수 필드가 즉시 나타납니다. 작성하는 동안 유효한 키워드, 필드 이름 및 구조를 제안하는 OpenAPI 및 Swagger에 최적화된 자동 완성 기능을 제공합니다.
이 자동 완성 기능은 스키마에 깊이 들어가서 additionalProperties인지 additionalItems인지 기억나지 않을 때 가장 중요합니다. 편집기는 스펙을 알고 있으므로 올바르게 유지하는 데 도움이 됩니다.
편집할 내용의 작은 부분:
paths:
/users/{userId}:
get:
summary: Get a user by ID
operationId: getUserById
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: A single user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
자동 파싱된 탐색 가능한 개요
원시 스펙 파일은 빠르게 길어집니다. 실제 API는 수천 줄에 달할 수 있습니다. 스펙 우선 모드는 파일을 시각적 개요로 자동 파싱하는 왼쪽 사이드바를 통해 이 문제를 해결합니다.
입력하는 동안 Apidog는 문서를 읽고 경로(paths), 작업(operations), 스키마(schemas) 및 컴포넌트(components)와 같은 탐색 가능한 구조를 구축합니다. 개요에서 어떤 노드를 클릭하면 편집기가 파일의 해당 위치로 이동합니다. 스크롤 대신 의미를 통해 탐색합니다. 개요는 스펙이 변경됨에 따라 실시간으로 업데이트되므로 항상 파일의 실제 내용을 반영합니다.
이것은 큰 openapi.yaml 파일을 관리 가능하게 유지합니다. 당신은 "1,847번째 줄"이 아니라 " POST /orders 작업"의 관점에서 생각하게 됩니다.
양방향 Git 동기화
이것이 이 모드의 핵심입니다. 스펙 우선 모드는 Git 저장소에 연결되어 스펙을 양방향으로 동기화합니다.
GitHub와 GitLab은 직접 지원됩니다. Azure DevOps는 일반 Git 연결을 통해 작동하며, 표준 Git 자격 증명을 사용하여 Apidog를 저장소에 연결할 수 있습니다. 연결되면 풀(pull)은 저장소 변경 사항을 편집기로 가져오고, 푸시(push)는 편집 내용을 저장소로 다시 보냅니다. Git이 공유 백본이므로 스펙은 팀의 모든 구성원에게 일관되게 유지됩니다.
| 제공업체 | 연결 방식 |
|---|---|
| GitHub | 직접 통합 |
| GitLab | 직접 통합 |
| Azure DevOps | 일반 Git 연결을 통해 |
특정 제공업체에 대한 집중적이고 단계별 가이드가 필요하다면, 저희 OpenAPI 스펙을 GitHub에 동기화하는 가이드에서 해당 흐름을 자세히 설명합니다.
커밋, 푸시 및 동기화 상태 표시기
그냥 저장하고 바라지 않습니다. 스펙 우선 모드는 이미 알고 있는 Git 모델을 따릅니다. 편집을 마치면 커밋 메시지를 작성하고 변경 사항을 커밋합니다. 그런 다음 연결된 저장소에 푸시합니다.
동기화 상태 표시기는 항상 정보를 제공합니다. 로컬 스펙이 저장소와 일치할 때 "방금 동기화됨"과 같은 상태를 표시하며, 푸시되지 않은 작업이 있을 때 변경됩니다. 당신이 보는 버전이 팀원이 보는 버전과 동일한지 항상 알 수 있습니다. 추측할 필요도, 오래된 스펙도 없습니다.
파일 변경 추적
커밋하기 전에 스펙 우선 모드는 정확히 어떤 것이 변경되었는지 보여줍니다. 파일 수준에서 수정 사항을 추적하고 각 항목을 수정됨, 추가됨, 삭제됨으로 표시합니다. Git 상태 출력을 검토하는 방식과 동일하게 변경 사항 세트를 검토합니다.
이것이 중요한 이유는 체크포인트를 제공하기 때문입니다. 올바른 편집 내용만 커밋하고 불필요한 것이 없는지 확인할 수 있습니다. 그리고 실험이 잘 되지 않았다고 판단되면, 푸시되지 않은 편집 내용을 저장소에 도달하기 전에 폐기할 수 있습니다. 이는 공유 히스토리를 깨끗하게 유지합니다. 로컬 탐색은 푸시하기로 결정할 때까지 로컬에 머무릅니다.
팀 권한이 있는 브랜치 및 저장소 범위 프로젝트
스펙 우선 프로젝트는 추상적으로 떠다니지 않습니다. 일반적으로 main과 같은 특정 저장소와 특정 브랜치에서 생성됩니다. 이러한 범위 지정은 프로젝트가 항상 Git의 실제 위치를 가리킨다는 것을 의미합니다. 스펙, 히스토리, 브랜치가 일치합니다.
팀 권한은 설정 중에 구성됩니다. 누가 프로젝트에 접근할 수 있고 무엇을 할 수 있는지 결정할 수 있으므로, 계약을 작업하는 사람들이 의도한 사람들과 일치합니다. 프로젝트가 저장소와 브랜치에 연결되어 있기 때문에, 접근 모델은 이미 Git에서 적용하고 있는 접근 모델을 반영할 수 있습니다.
스펙 우선 모드 설정 방법
설정은 짧고 선형적인 흐름입니다. 다음 단계를 따르십시오. 스크린샷과 함께 보려면 공식 가이드는 docs.apidog.com/spec-first-mode-beta-2058268m0에 있습니다.
- 모드를 전환합니다. Apidog에서 API 모듈을 엽니다. 모듈의 왼쪽 하단에서 모드 토글을 찾아 디자인 우선(Design-First)에서 스펙 우선 모드(Spec-First Mode)로 전환합니다.
- Git 제공업체를 연결합니다. GitHub 또는 GitLab을 직접 인증합니다. Azure DevOps의 경우, Git 자격 증명을 사용하여 일반 Git 연결을 설정합니다.
- 저장소에서 프로젝트를 생성합니다. 스펙을 포함하는 저장소를 선택하고 일반적으로
main브랜치를 선택합니다. Apidog는 새 프로젝트를 해당 저장소와 브랜치에 범위 지정합니다. - 팀 권한을 구성합니다. 설정 중에 누가 프로젝트에 접근할 수 있고 무엇을 변경할 수 있는지 설정합니다.
- 스펙을 편집합니다. IDE 스타일 편집기에서
openapi.yaml또는openapi.json을 엽니다. 왼쪽의 개요를 사용하여 탐색합니다. 작성 시 유효성 검사 및 자동 완성 기능을 활용하십시오. - 변경 사항을 커밋합니다. 명확한 커밋 메시지를 작성합니다. 먼저 추적된 변경 사항을 검토합니다. 유지하고 싶지 않은 것은 폐기합니다.
- 저장소에 푸시합니다. 연결된 브랜치에 커밋을 푸시합니다.
- 동기화를 확인합니다. 동기화 상태 표시기를 확인합니다. "방금 동기화됨"이라고 표시되면 스펙과 저장소가 일치하는 것입니다.
이것이 전체 루프입니다: 전환, 연결, 생성, 편집, 커밋, 푸시, 확인.
일반적인 일상 워크플로우
설정 후 이 모드가 실제로 어떻게 느껴지는지 소개합니다.
하루를 시작할 때 연결된 브랜치에서 최신 내용을 풀(pull)하여, 편집기가 팀원들이 밤새 병합한 내용을 반영하도록 합니다. 개요를 열고 작업 중인 작업(operation)으로 클릭하여 YAML 편집을 시작합니다. 새 엔드포인트에 요청 본문이 필요하므로 스키마를 정의합니다. 자동 완성 기능은 필드 이름을 올바르게 작성하는 데 도움을 주며, 유효성 검사는 문제가 되기 전에 $ref의 오타를 잡아냅니다.
엔드포인트가 괜찮아 보이면, 파일 변경 추적을 확인합니다. 수정 사항을 보여줍니다. Add POST /invoices endpoint와 같은 커밋 메시지를 작성하고 커밋한 다음 푸시합니다. 상태 표시기는 "방금 동기화됨"으로 바뀝니다. 팀원은 일반적인 풀 리퀘스트에서 변경 사항을 검토하는데, 이는 스펙이 다른 모든 것과 마찬가지로 Git에 있기 때문입니다.
해당 흐름에서 추가할 수 있는 내용은 다음과 같습니다:
components:
schemas:
Invoice:
type: object
required: [id, amount, currency]
properties:
id:
type: string
format: uuid
amount:
type: integer
description: Amount in the smallest currency unit
currency:
type: string
example: USD
status:
type: string
enum: [draft, sent, paid]
전체 사이클은 당신이 신뢰하는 도구 내에서 이루어집니다. 스펙은 코드이며, 당신은 그것을 코드처럼 취급합니다.
스펙 우선 모드는 누가 사용해야 하나요?
스펙 우선 모드는 일부 팀에 다른 팀보다 더 적합합니다. 당신의 팀이 어떤 종류인지 솔직하게 판단하십시오.
팀이 이미 Git 환경에 익숙하다면 스펙 우선 모드를 사용하십시오. 풀 리퀘스트에서 API 계약을 검토하거나, 서비스 코드와 함께 스펙 버전을 관리하고 싶거나, 엔지니어가 YAML을 직접 편집하는 것을 선호한다면 이 모드는 마찰을 줄여줍니다. OpenAPI 문서를 일등 시민 아티팩트로 취급하는 백엔드 및 플랫폼 팀에 매우 적합합니다.
안내되고 시각적인 경험을 원한다면 대신 디자인 우선 모드를 선택하십시오. 비엔지니어가 디자인에 기여하거나, YAML을 작성하는 것보다 폼을 클릭하는 것을 선호하는 사람들은 그곳에서 더 빠르게 작업할 수 있습니다. 제품 및 디자인 팀이 엔드포인트에 의견을 제시하는 혼합 팀은 종종 시각 편집기를 선호합니다. 정답은 없습니다. 팀이 실제로 일하는 방식에 맞는 모드를 선택하십시오. 저희 비교 게시물에서 이 결정에 대해 더 자세히 다룹니다.
제한 사항 및 베타 노트
스펙 우선 모드는 베타 버전입니다. 이 단어는 실제적인 의미를 지니므로, 그에 따라 기대를 설정하십시오.
베타 버전이므로 이 기능은 아직 발전 중입니다. Apidog가 피드백을 기반으로 모드를 개선함에 따라 기능과 동작이 변경될 수 있습니다. 현재 직접 제공업체 통합은 GitHub와 GitLab을 지원하며, Azure DevOps는 전용 통합보다는 일반 Git 연결에 의존합니다. 팀이 특정 Git 제공업체나 워크플로우에 의존한다면, 중요한 프로젝트를 이 모드에 적용하기 전에 요구 사항에 맞는지 확인하십시오.
스펙이 라이브 저장소와 동기화되므로, 일반적인 Git 규율이 적용됩니다. 신중하게 커밋하고, 의도적으로 푸시하며, 편집 내용이 배포되어서는 안 될 때는 폐기 옵션을 사용하십시오. 파일 변경 추적 및 동기화 표시기는 안전을 위해 존재하지만, 깨끗한 히스토리에 대한 책임은 여전히 사용자에게 있습니다. 베타 버전을 메인 브랜치에 영향을 미치는 새로운 도구를 다루는 방식과 동일하게 취급하십시오: 먼저 중요하지 않은 저장소에서 시도한 다음, 흐름을 신뢰하게 되면 확장하십시오.
베타 버전의 장점은 영향력입니다. 초기 피드백은 기능이 나아갈 방향을 결정하므로, 워크플로우에 빠진 것이 있다면 보고할 가치가 있습니다.
자주 묻는 질문(FAQ)
스펙 우선 모드는 무료인가요?
스펙 우선 모드는 Apidog 내의 베타 기능입니다. 접근 권한은 Apidog 플랜에 따라 다르므로, 현재 플랜과 베타 상태를 기준으로 모드의 가용성을 확인하십시오. 베타 버전이므로, 가장 간단한 방법은 API 모듈에서 활성화하여 계정에서 사용 가능한지 확인하는 것입니다.
어떤 Git 제공업체가 지원되나요?
GitHub와 GitLab은 직접 통합을 통해 지원됩니다. Azure DevOps는 일반 Git 연결을 통해 작동하며, 이는 표준 Git 자격 증명을 사용하여 Apidog를 저장소에 연결합니다. 해당 일반 연결은 제공업체별 API가 아닌 표준 Git에 의존하므로, 다른 Git 호스트도 작동할 수 있습니다.
디자인 우선 모드로 다시 전환할 수 있나요?
네. 모드 토글은 API 모듈의 왼쪽 하단에 있으며, 그곳에서 스펙 우선 모드와 디자인 우선 모드 사이를 전환할 수 있습니다. 고정되지 않습니다. 당면한 프로젝트에 가장 적합한 모드를 선택하십시오.
어떤 파일 형식을 편집할 수 있나요?
IDE 스타일 편집기에서 원시 YAML 또는 JSON으로 OpenAPI 문서를 편집합니다. 편집기는 OpenAPI와 Swagger 모두에 대해 구문 강조 표시, 스키마 유효성 검사 및 자동 완성 기능을 제공하므로, 어떤 형식으로 작성하든 정확성을 유지할 수 있습니다.
푸시되지 않은 편집 내용은 어떻게 되나요?
푸시되지 않은 편집 내용은 푸시하기 전까지 로컬에 유지됩니다. 스펙 우선 모드는 모든 변경 사항을 수정됨, 추가됨 또는 삭제됨으로 추적하며, 동기화 표시기는 저장소에 도달하지 않은 작업이 있을 때 알려줍니다. 변경 사항에 반대하기로 결정하면, 푸시하기 전에 폐기하면 공유 히스토리에 포함되지 않습니다.
결론
Apidog 스펙 우선 모드는 OpenAPI 편집기와 Git을 한 곳에 통합합니다. YAML 또는 JSON으로 스펙을 편집하고, 자동 파싱된 개요를 통해 탐색하며, 입력하는 동안 유효성을 검사하고, GitHub, GitLab 또는 Azure DevOps와 양방향으로 동기화합니다. 커밋 메시지, 푸시, 변경 추적 및 명확한 동기화 표시기는 API 계약에 적용된, 이미 알고 있는 Git 워크플로우를 제공합니다.
이것은 베타 버전이며, 스펙을 소스 코드로 취급하려는 Git-네이티브 팀을 대상으로 합니다. 만약 당신이 그런 팀이라면, 이 모드를 진지하게 고려해볼 가치가 있습니다. API 모듈에서 활성화하고, 저장소를 연결한 다음, 작은 편집-커밋-푸시 사이클을 시도하여 흐름을 느껴보십시오. 준비가 되면, 문서에서 스펙 우선 모드를 시도하고 신뢰하는 저장소에 연결하십시오.