제가 함께 일했던 모든 API 팀에는 두 가지 진영이 있었습니다.
한쪽은 OpenAPI 스펙을 직접 작성하여 specs/ 디렉터리에 커밋하고, Git을 단일 진실 공급원으로 취급합니다. 다른 한쪽은 시각적 디자이너를 클릭하여 스펙을 내보내고, CI가 불평할 때마다 지난 화요일 이후로 두 표현 간에 누적된 불일치를 패치합니다.
저는 두 진영 모두에 살아봤습니다. 첫 번째 진영은 첫날에는 느리지만 90일째에는 빠릅니다. 두 번째 진영은 그 반대입니다. 그리고 한 달 전까지만 해도 제가 가장 많이 사용하는 API 디자인 도구인 Apidog는 사실상 두 번째 진영에만 맞춰져 있었습니다. 시각적 디자이너는 훌륭했습니다. YAML 왕복 기능은 코드 검토에서 옹호해야 하는 기능이었죠.
그러다가 4월 중순, 새 프로젝트 대화 상자에 스펙 우선 모드 (베타)가 나타났습니다. 저는 출시일에 의도적으로 이에 대해 쓰지 않았습니다. 먼저 실제 프로젝트에 사용해보고 싶었고, 초기 버그가 드러날 만큼 충분히 기다리고 싶었습니다. 한 달은 대략 적절한 시간이죠. 이 게시물은 제가 제 사이드 프로젝트 중 하나의 OpenAPI 스펙을 가지고 베타 버전을 한나절 사용해 본 후 알게 된 내용입니다. 동료가 시도하기 전에 제가 이야기해 줄 내용과 이 모드가 어디에 적합하고 어디에 적합하지 않은지에 대한 것입니다.
스펙 우선 모드가 실제로 변경하는 것
간단히 말해: Apidog는 이제 두 가지 프로젝트 모드를 가지며, 그 밑단에서는 완전히 다른 제품입니다.
기본 모드는 대부분의 사람이 아는 것입니다. '+ 새 프로젝트'를 클릭하면 폴더 트리와 시각적 양식이 나타나고, 필드를 채워 엔드포인트를 구축합니다. OpenAPI 스펙은 내부적으로 생성됩니다. 특히 강력한 YAML 습관이 없는 팀에게는 효과적입니다.
스펙 우선 모드는 양식 편집기를 원시 .yaml 및 .json 파일에 대한 실제 코드 편집기로 대체하며, Git 저장소와의 양방향 동기화를 제공합니다. OpenAPI 스펙은 클릭의 직렬화가 아니라 디스크 상의 파일입니다. 구문 강조, OpenAPI 스키마에 대한 자동 완성, 그리고 입력하는 동안 코드에서 사이드바에 엔드포인트 개요를 구성하는 "실시간 디렉터리 파싱" 창이 있습니다.
만약 제가 회의적인 사람에게 이것을 시연한다면, 마지막 세부 사항을 먼저 언급할 것입니다. 시각적 디자이너가 존재하는 이유는 YAML이 어렵기 때문이 아니라, YAML이 이미 스크롤을 지나치기 전까지는 구조를 숨기기 때문입니다. Apidog의 개요 보기는 파일을 포기하지 않고도 이 문제를 해결합니다. 스펙을 작성하면 내비게이션을 얻습니다. 두 가지가 화면에 공존합니다.
만약 가설이 있다면, 그것은 스펙 우선 개발이 텍스트 편집기를 선호하는 것이 아니었다는 것입니다. 그것은 누가 아티팩트를 소유하는지에 관한 것이었습니다. 스펙 우선 모드는 아티팩트를 저장소의 파일로 만듭니다. UI는 그 파일의 창이며, 그 파일의 래퍼가 아닙니다.
종단 간 설정
제가 걸었던 경로입니다. 10분도 채 걸리지 않았고, 대부분은 Git 권한 부여에 소요되었습니다.
1. 올바른 모드로 프로젝트 생성. 프로젝트 화면에서, + 새 프로젝트 → 일반 → 스펙 우선 모드. 지난 1년 동안 자동 조종 모드로 프로젝트를 생성해 왔다면 모드 선택기를 놓치기 쉽습니다. 일반 모드는 "권장"으로 표시되어 눈이 두 번째 타일을 그냥 지나칠 수 있습니다. 여기서는 속도를 늦추세요.
2. Git 저장소에 연결. Git 저장소와 연결로 스크롤하여 공급자를 승인합니다. 저는 GitHub를 사용했습니다; 문서는 다른 것들도 다룹니다. 그런 다음 조직, 저장소, 그리고 메인 브랜치를 선택합니다. Apidog는 해당 브랜치에 있는 스펙 파일을 작업 복사본으로 동기화합니다.
3. 프로젝트 구성. 프로젝트 이름을 입력하고, 팀 권한을 설정한 다음, 생성합니다. 첫 번째 동기화는 저장소에 있는 .yaml 및 .json 파일을 Apidog 작업 공간으로 가져옵니다.
4. 스펙을 양식이 아닌 파일처럼 편집. YAML 파일 중 하나를 엽니다. 실제 편집기, 스키마 인식 자동 완성, 그리고 입력하는 동안 사이드바에 나타나는 엔드포인트 개요를 얻습니다. OpenAPI 확장 기능을 사용하여 VS Code에서 시간을 보낸 적이 있다면 익숙할 것입니다. 단, 개요는 탐색에 연결되어 있으며, 엔드포인트를 클릭하면 올바른 줄로 이동합니다.
5. 커밋 및 푸시. 오른쪽 상단, 커밋 및 푸시. 대화 상자는 수정된 파일을 나열하는 변경 사항 섹션, 커밋 메시지 필드, 그리고 두 개의 버튼: 푸시 또는 모든 변경 사항 폐기로 열립니다. 별도의 스테이징 단계는 없습니다. 변경 사항에 있는 모든 것이 커밋됩니다. 이는 의도적인 단순화이며, 대부분의 스펙 편집 워크플로우에는 올바른 선택입니다.
6. 동기화 표시기 확인. 왼쪽 하단 모서리 — 그림 1에서 방금 동기화됨으로 볼 수 있습니다. 로컬 편집 내용이 푸시되었는지, 풀되었는지, 아니면 원격과 동기화되지 않았는지 알려줍니다. 저는 이것을 화면 한쪽 구석에 열어 두었는데, 모달 대화 상자보다 더 신뢰하게 되었습니다. 표시기가 녹색이면, 당신과 저장소는 일치합니다.
이것이 전체 표면 영역입니다. 6단계, 구성할 별도의 동기화 엔진 없음, 설치할 플러그인 없음.
문서에 없는 제가 발견한 것
하루 아침에 찔러보면서 플래그를 달 만한 세 가지입니다.
개요 보기가 예상보다 빠르게 업데이트됩니다. 저는 이전에 여러 "라이브 OpenAPI 편집기"를 사용해 보았는데, 대부분은 저장할 때 다시 파싱하므로 엔드포인트를 추가하고 사이드바에서 보는 데 30초의 지연이 있었습니다. Apidog의 개요는 제가 입력하는 동안 업데이트되었고, 거의 즉각적이어서 확인을 멈췄습니다. 작게 들리겠지만, 그렇지 않습니다. 이는 개요를 탐색 도우미로 신뢰하는 것과 상태 보고서로 확인하는 것의 차이입니다.
Git 통합은 진정으로 양방향입니다. Apidog가 열려 있는 동안 제 로컬 클론에서 동일한 파일을 편집하고 터미널에서 푸시했습니다. Apidog는 이를 감지했고, 동기화 표시기는 "뒤쳐짐"으로 바뀌었으며, 한 번의 클릭으로 병합 대화 상자 없이 변경 사항을 편집기로 가져왔습니다. 문서가 약속하는 양방향 동기화는 마케팅 요약이 아닌 실제 경험입니다. Vim 외에는 아무것도 사용하지 않으려는 동료가 있다면, 그들은 Vim을 계속 사용할 수 있고, 당신은 Apidog를 계속 사용할 수 있으며, 저장소의 파일은 두 사람 모두가 편집하는 단일 개체로 유지됩니다.
동일한 프로젝트에서 시각적 디자이너로 돌아갈 수 있는 탈출구는 없습니다. 이것은 의도적인 것이지만, 커밋하기 전에 알아두는 것이 좋습니다. 프로젝트 생성 시 스펙 우선 모드를 선택하면 해당 프로젝트는 스펙 우선입니다. 기본 데이터 모델이 다르기 때문에 프로젝트를 도중에 전환할 수 없습니다. 동일한 스펙에서 두 모드를 모두 원하는 팀의 경우, 워크플로우는 다음과 같습니다: 스펙을 저장소에 유지하고, 스펙 우선 프로젝트를 가리키게 한 다음, 시각 모드 사용자가 동일한 소스에서 가져오는 별도의 프로젝트를 열도록 합니다. 매끄럽지는 않지만, 실행 가능합니다.
어디에 적합하고 어디에 적합하지 않은가
저는 이것을 프로덕션에서 사용할 것입니다. 이것이 제가 드릴 수 있는 가장 직접적인 답변입니다. 실제 편집기, OpenAPI 스키마를 준수하는 자동 완성, 그리고 제가 신뢰할 수 있는 동기화 표시기의 조합은 제가 2년 동안 Apidog에서 원했던 것입니다.
하지만 이것이 누구를 위한 것인지에 대한 솔직한 버전입니다.
OpenAPI를 직접 작성하고 있거나 원한다면 적합합니다. CI가 spectral lint를 실행하거나 스펙에서 클라이언트 SDK를 생성해야 하고 스펙이 어쨌든 Git에 있어야 한다면 적합합니다. 팀에 VS Code에서 YAML 파일에 대해 풀 리퀘스트를 열었을 엔지니어가 있고, 그들에게 키보드를 포기하게 하지 않고 모두가 하나의 도구로 수렴하기를 원한다면 적합합니다. 그리고 "Apidog의 스펙"과 "저장소의 스펙" 사이의 불일치를 아무도 신뢰하지 않는 make export 단계로 관리해 왔다면 특히 잘 맞습니다.
팀이 OpenAPI를 한 번도 접해본 적이 없고 시각적 디자이너가 기여할 수 있는 유일한 이유라면 적합하지 않습니다. 그런 팀에게는 기본 모드가 여전히 올바른 선택입니다. 스펙 우선 모드는 온보딩 용이성을 충실도와 교환하며, 대부분의 기여자가 API 전문가가 아닐 때는 그 교환이 잘못된 것입니다.
또한, 동일한 프로젝트에서 두 모드를 혼합해야 하는 팀에게는 아직 적합하지 않습니다. 이 베타는 해당 측면에서 진정한 베타입니다. 다음 몇 릴리스 동안 이것이 완화될 것으로 예상합니다.
핵심 요점
스펙 우선 개발은 API 디자인 도구를 사용하지 않는 것을 의미했습니다. YAML에서 살면서 테스트 러너와 모의 서버를 포기하거나, 시각적 디자이너에서 살면서 Git을 단일 진실 공급원으로 포기해야 했습니다. 스펙 우선 모드의 흥미로운 점은 Apidog가 더 이상 선택을 요구하지 않는다는 것입니다.
저장소의 파일은 편집기의 파일입니다. 개요는 뷰이지, 상태가 아닙니다. Git 동기화는 와이어이지, 기능이 아닙니다. API 플랫폼이 스펙 우선을 내보내기 옵션으로 취급하지 않고 진지하게 받아들이기를 기다려왔다면, 이것이 바로 제가 시도해 볼 만한 것입니다.
베타 버전은 오늘 새 프로젝트 대화 상자에서 사용할 수 있습니다. Apidog를 다운로드하고, 생성 시 스펙 우선 모드를 선택한 다음, 이미 신뢰하는 저장소를 가리키세요. 첫 번째 커밋은 10분이 걸립니다. 계속 사용할지 여부에 대한 결정은 약 일주일이 걸립니다.
button