코드는 Git에 있습니다. CI 파이프라인, 검토 및 릴리스 이력도 Git에 있습니다. 그런데 왜 API 사양은 다른 곳에 있을까요?
Git 기반 API 워크플로는 OpenAPI 정의를 코드와 동일한 위치에 유지합니다. 사양을 일반 YAML 또는 JSON 파일로 편집하고, 커밋하고, 다른 모든 것에 사용하는 것과 동일한 검토 프로세스를 거쳐 푸시합니다. 별도의 클라우드 데이터베이스가 필요 없습니다. 내보내기-가져오기 반복 작업도 없습니다. 사양은 저장소에 있는 또 하나의 파일일 뿐입니다.
Git 기반 API 워크플로의 의미
Git 기반 API 워크플로는 API 사양을 코드로 취급합니다. OpenAPI 파일은 서비스와 함께 저장소에 있습니다. 모든 변경은 커밋입니다. 모든 커밋에는 작성자, 메시지, 차이점이 있습니다.
이는 소스 코드에서 이미 기대하는 세 가지를 제공합니다.
- 버전 기록. 누가 언제 엔드포인트를 변경했는지 확인할 수 있습니다.
git blame은 사양에서도 작동합니다. - 브랜칭 및 검토. 사양 변경은 풀 리퀘스트를 통해 이루어집니다. 검토자는 병합 전에 정확한 차이점을 확인합니다.
- 단일 진실 공급원.
main의 파일은 계약입니다. 도구, 문서, 목업은 모두 이 파일에서 읽어옵니다.
이것이 사양 우선(spec-first) API 워크플로의 핵심 아이디어입니다. 사양이 선행되고 구현이 따릅니다. 이 관행에 대한 자세한 내용은 사양 우선 API 개발에 대한 가이드를 참조하세요.
반대 접근 방식은 독점적인 클라우드 앱 내에 사양을 저장합니다. 이는 팀이 성장하거나 프로세스가 성숙해질 때까지는 작동하지만, 그 이후에는 문제점이 드러납니다.
클라우드 종속 API 사양의 문제점
대부분의 API 디자인 도구는 사양을 자체 데이터베이스에 보관합니다. 사용자는 UI를 통해 편집합니다. 소유하고 있다고 생각하는 "파일"은 실제로는 다른 사람 시스템의 행입니다.
이것은 예측 가능한 방식으로 무너집니다.
검토는 두 곳에서 이루어집니다. 코드 변경은 GitHub를 통해 이루어집니다. 사양 변경은 자체 주석 및 기록을 가진 별도의 도구를 통해 이루어집니다. 검토자는 컨텍스트를 전환합니다. 승인이 동기화되지 않을 수 있습니다.
차이점이 숨겨집니다. 사양이 클라우드 데이터베이스에 있는 경우, 풀 리퀘스트에서 깔끔한 줄별 차이점을 볼 수 없습니다. 실제로 무엇이 변경되었는지 전혀 모른 채 "디자인 v3"를 승인하게 됩니다.
내보내기가 번거로워집니다. 사양을 CI로 가져오려면 내보낸 다음, 내보낸 파일을 커밋하고, 그 사이에 아무도 클라우드 사본을 편집하지 않기를 바랍니다. 두 가지 진실의 출처, 피할 수 없는 하나의 충돌입니다.
자동화는 당신과 싸웁니다. 린터, 계약 테스트 및 코드 생성기는 디스크에 있는 파일을 원합니다. 클라우드에 잠긴 사양은 이러한 작업이 실행되기 전에 가져오기 단계를 강제합니다.
API 사양을 코드로 취급하면 이 모든 것이 제거됩니다. 파일이 사양입니다. Git이 기록입니다. 기존 파이프라인이 나머지를 처리합니다. 이 원칙에 대해서는 코드형 API 사양에서 자세히 다룹니다.
Apidog Spec-First 모드 작동 방식
Spec-First 모드는 이미 커밋과 브랜치를 생각하는 팀을 위해 만들어졌습니다. API를 원시 YAML 또는 JSON 파일로 설계하면, Apidog가 해당 파일을 Git 저장소와 양방향으로 동기화합니다.
다음과 같은 이점을 얻을 수 있습니다.
IDE 스타일 OpenAPI 편집기
양식이 아닌 코드 편집기에서 사양을 작성합니다. 이 편집기는 IDE에서 기대할 수 있는 편리함을 제공합니다.
- YAML 및 JSON에 대한 구문 강조.
- OpenAPI 및 Swagger 스키마에 대한 유효성 검사로, 입력하는 동안 오류가 표시됩니다.
- OpenAPI 키워드, 유형 및 참조에 대한 자동 완성.
정확한 파일을 계속 제어합니다. 숨겨진 필드나 UI 전용 메타데이터가 없습니다.
원시 YAML/JSON 파일
사양은 실제 파일입니다. 다음은 작은 예시입니다.
openapi: 3.1.0
info:
title: Orders API
version: 1.2.0
paths:
/orders/{orderId}:
get:
summary: Get an order by ID
operationId: getOrder
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
"200":
description: Order found
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
"404":
description: Order not found
components:
schemas:
Order:
type: object
properties:
id:
type: string
status:
type: string
enum: [pending, shipped, delivered]
이 파일이 저장소에 저장됩니다. 편집한 내용이 커밋됩니다.
자동 구문 분석 및 탐색 가능한 개요
입력하는 동안 Apidog는 파일을 구문 분석하고 왼쪽 사이드바에 시각적 개요를 생성합니다. 경로, 작업 및 스키마는 클릭할 수 있는 트리 형태로 나타납니다. 디자인 도구의 가독성과 원시 파일의 정밀도를 동시에 얻을 수 있습니다.
긴 사양도 탐색 가능하게 유지됩니다. 수백 줄을 스크롤하지 않고도 엔드포인트로 이동할 수 있습니다.
양방향 Git 동기화
Spec-First 모드는 Git 제공업체에 연결하고 양방향으로 변경 사항을 동기화합니다. GitHub 및 GitLab을 직접 지원하며, Git 연결을 통해 Azure DevOps도 지원합니다.
팀원이 푸시한 변경 사항을 가져옵니다. Apidog 편집기에서 로컬로 편집합니다. 그런 다음 동일한 브랜치에 커밋하고 푸시합니다. 저장소와 작업 공간이 정렬된 상태를 유지합니다.
커밋, 푸시 및 동기화 상태 표시기
Git을 관리하기 위해 Apidog를 떠날 필요가 없습니다. 변경 사항을 스테이징하고, 커밋 메시지를 작성하고, 푸시합니다. 동기화 상태 표시기가 현재 상태를 알려줍니다. 성공적으로 푸시되면 "방금 동기화됨"과 같이 표시됩니다. 푸시하기 전에 마음을 바꾸면 푸시되지 않은 편집을 취소하고 마지막으로 동기화된 상태로 돌아갈 수 있습니다.
이 양방향 동기화는 Git 기반 API 워크플로의 핵심입니다. GitHub 측면의 자세한 설명은 OpenAPI 사양을 GitHub에 동기화를 참조하세요.
설정 단계별 설명
다음은 빈 저장소에서 동기화된 사양으로 가는 방법입니다. 전체 참조는 Spec-First 모드 문서에 있습니다.
- 저장소에서 프로젝트를 생성합니다. Apidog에서 새 Spec-First 프로젝트를 시작하고 Git 제공업체를 연결합니다. API 사양을 포함하는 저장소를 선택하고 추적할 브랜치(일반적으로
main)를 선택합니다. Apidog는 기존 사양 파일을 편집기로 가져옵니다.
- 사양을 편집합니다. 편집기에서 OpenAPI 파일을 엽니다. 엔드포인트를 추가하고, 스키마를 조정하고, 응답을 수정합니다. 구문 강조, 유효성 검사 및 자동 완성 기능이 작성하는 동안 안내합니다. 파일이 변경됨에 따라 왼쪽 사이드바 개요가 업데이트됩니다.
- 수정, 추가 및 삭제된 파일을 추적합니다. Apidog는 마지막 동기화 이후 변경한 파일을 보여줍니다. 수정, 추가 및 삭제된 파일은 커밋에 포함될 내용을 정확히 알 수 있도록 플래그가 지정됩니다.
- 커밋 메시지를 작성합니다. 다른 Git 클라이언트에서와 마찬가지로 변경 사항을 명확한 언어로 설명합니다. "getOrder에 404 응답 추가"는 "사양 업데이트"보다 좋습니다.
- 푸시합니다. 커밋을 추적된 브랜치로 보냅니다. 이제 팀원과 CI 파이프라인은 새 버전을 볼 수 있습니다.
- "방금 동기화됨"을 확인합니다. 동기화 상태 표시기가 푸시를 확인하는지 확인합니다. "방금 동기화됨"으로 표시되면 로컬 편집 내용과 원격 브랜치가 일치합니다. 여기에서 변경 사항은 일반적인 풀 리퀘스트 및 검토 프로세스를 통해 진행됩니다.
이것이 전체 루프입니다: 가져오기, 편집, 커밋, 푸시, 확인. 내보내기 단계가 없습니다. 두 번째 진실 공급원이 없습니다.
사양 우선 모드 vs 디자인 우선 모드
Apidog는 두 가지 작업 방식을 지원합니다. 차이점은 사양이 어디에 있고 어떻게 편집하는지에 있습니다.
| Spec-First 모드 (베타) | Design-First 모드 | |
|---|---|---|
| 사양 저장소 | Git의 원시 YAML/JSON 파일 | Apidog 클라우드 프로젝트 |
| 주요 편집기 | IDE 스타일 코드 편집기 | 시각적 양식 기반 UI |
| 버전 관리 | 네이티브 Git (커밋, 브랜치, 차이점) | Apidog 기록 및 브랜치 |
| 양방향 Git 동기화 | 예 (GitHub, GitLab, Azure DevOps) | 내보내기/가져오기를 통해 |
| 가장 적합한 경우 | Git을 주로 사용하는 팀 | 시각적 워크플로를 선호하는 팀 |
어떤 모드도 "더 좋다"고 할 수는 없습니다. 그들은 다른 습관에 맞습니다. 검토 및 릴리스 프로세스가 이미 Git에서 실행된다면 Spec-First 모드가 그 차이를 없애줍니다. 팀이 시각적으로 설계하고 원시 OpenAPI를 거의 건드리지 않는다면 Design-First 모드가 더 적합할 수 있습니다.
언제 사용해야 할까요?
다음과 같은 경우 Spec-First 모드를 사용하세요.
- 사양이 풀 리퀘스트 및 코드 검토를 거쳐야 할 때.
- API 계약에
git blame및 실제 커밋 기록을 원할 때. - CI가 디스크에 있는 파일이 필요한 사양 린팅, 계약 테스트 또는 코드 생성을 실행할 때.
- 여러 엔지니어가 사양을 편집하고 깔끔하고 병합 가능한 차이점을 원할 때.
- 한 도구에서 다른 도구로 내보내는 것에 지쳤을 때.
팀이 원시 OpenAPI를 작성하지 않고 API를 설계하거나 비엔지니어가 사양을 소유하고 양식 기반 편집기를 선호하는 경우 시각적, 클라우드 우선 접근 방식을 고수하세요.
자주 묻는 질문
Git 기반 API 워크플로란 무엇인가요?
Git 기반 API 워크플로는 OpenAPI 사양을 Git 저장소의 파일로 저장하고 커밋, 브랜치, 풀 리퀘스트를 통해 모든 변경 사항을 관리합니다. 사양은 애플리케이션 코드와 동일한 검토 및 버전 제어 프로세스를 따르므로 단일 진실 공급원이 됩니다.
Apidog Spec-First 모드는 GitHub와 GitLab을 지원하나요?
예. Spec-First 모드는 GitHub 및 GitLab과 직접 양방향으로 동기화됩니다. Azure DevOps는 Git 연결을 통해 지원됩니다. 저장소를 연결하고 브랜치를 선택하면 Apidog가 편집 내용과 원격을 동기화된 상태로 유지합니다.
OpenAPI 파일을 원시 YAML 또는 JSON으로 편집할 수 있나요?
예. Spec-First 모드는 원시 YAML 및 JSON용 IDE 스타일 편집기를 제공하며, OpenAPI 및 Swagger에 대한 구문 강조, 스키마 유효성 검사 및 자동 완성을 지원합니다. 왼쪽 사이드바 개요는 파일을 자동으로 구문 분석하여 대규모 사양을 빠르게 탐색할 수 있도록 합니다.
Spec-First 모드와 Design-First 모드의 차이점은 무엇인가요?
Spec-First 모드는 사양을 Git의 파일로 유지하고 양방향 동기화를 통해 코드 편집기에서 편집합니다. Design-First 모드는 시각적 양식 기반 편집기를 사용하여 Apidog 클라우드 프로젝트에 사양을 유지합니다. 워크플로가 이미 Git에서 실행되는 경우 Spec-First를 선택하세요.
결론
Git 기반 API 워크플로는 코드와 API 계약 간의 분리를 종식시킵니다. 사양은 파일이 되고, 파일은 커밋이 되며, 커밋은 이미 신뢰하는 검토 프로세스를 거칩니다.
Apidog Spec-First 모드는 이를 현실로 만들기 위한 IDE 스타일 편집기, 탐색 가능한 개요, 양방향 Git 동기화를 제공합니다. 원시 YAML 또는 JSON을 편집하고, 명확한 메시지를 커밋하고, 푸시하면 "방금 동기화됨" 상태를 볼 수 있습니다.
Spec-First 모드를 사용해보고 API 사양을 Git으로 가져오세요.