Apidog 스펙 우선 vs 디자인 우선: 어떤 모드를 사용해야 할까요?

Apidog의 API 모듈은 API 계약이라는 동일한 대상을 두 가지 방법으로 구축할 수 있도록 합니다. 하나는 시각적 양식을 사용하고, 다른 하나는 Git에 연결된 원시 코드 편집기를 사용합니다. 둘 다 유효한 OpenAPI를 생성합니다. 차이점은 팀이 일상적으로 작업하는 방식이며, 어떤 방식이 적합한지는 도구보다는 팀의 습관에 더 많이 달려 있습니다.

이 가이드에서는 Apidog에서 디자인-우선(design-first) 대 사양-우선(spec-first) 결정에 대해 설명합니다. 각 모드가 무엇인지, Git을 어떻게 다루는지, 그리고 어떤 팀이 어떤 모드를 선호하는지 등을 다룹니다. API 모듈의 왼쪽 하단에 있는 단일 토글을 통해 모드 간에 전환할 수 있으므로 선택이 영구적이지는 않습니다. 하지만 올바른 기본값을 선택하면 마찰을 줄일 수 있습니다.

두 가지 철학

모드 이전에 사고방식이 중요합니다. 두 접근 방식 모두 한 가지 규칙을 공유합니다. 구현을 작성하기 전에 API 계약을 정의해야 한다는 것입니다. 계약이 진실의 원천입니다. 코드, 테스트, 목업, 문서 등 모든 것이 계약에서 파생됩니다.

디자인-우선(Design-first)은 구조화된 인터페이스를 통해 계약을 형성하는 것을 의미합니다. 양식과 드롭다운을 통해 엔드포인트, 매개변수 및 스키마를 추가합니다. 유효한 값만 입력할 수 있으므로 도구가 출력의 유효성을 보장합니다.

사양-우선(Spec-first, 종종 계약-우선(contract-first)이라고도 함)은 사양 파일을 통해 직접 계약을 작성하는 것을 의미합니다. YAML 또는 JSON 형식의 OpenAPI가 해당됩니다. 사양이 작업 표면입니다. 소스 코드처럼 편집합니다.

이 용어들은 실제로 중복됩니다. "계약-우선"과 "사양-우선"은 거의 동의어이며, 많은 팀이 "디자인-우선"을 계약이 코드보다 선행하는 모든 접근 방식을 느슨하게 지칭하는 데 사용합니다. 여기서 유용한 구체적인 구분은 다음과 같습니다. Apidog에서는 한 모드가 양식을 제공하고 다른 모드는 텍스트 편집기를 제공합니다. 이것이 선택할 때 중요한 기준입니다.

이 두 가지를 디자인-우선 대 코드-우선 API 개발과 분리하는 것이 중요합니다. 코드-우선은 구현의 주석 으로부터 사양을 생성하므로 코드가 선행합니다. Apidog의 두 모드 모두 계약을 코드보다 우선시합니다. 단지 작성 방식에 대한 의견이 다를 뿐입니다. 사양을 버전 관리되는 아티팩트로 취급하는 더 넓은 관점에 대해서는 Git-native API 워크플로우 개요를 참조하십시오.

Apidog 디자인-우선 모드

디자인-우선 모드는 시각적 디자이너입니다. 가이드 인터페이스를 통해 엔드포인트를 구축합니다. 메서드를 선택하고, 경로 이름을 지정하고, 쿼리 및 경로 매개변수를 추가하고, 트리 편집기를 통해 요청 및 응답 스키마를 정의하고, 예시를 첨부합니다. Apidog는 백그라운드에서 기본 OpenAPI를 자동으로 렌더링합니다.

이 모드는 대부분의 팀에게 기본값이며, 그럴 만한 이유가 있습니다. OpenAPI 구문을 기억할 필요가 없습니다. 스키마 편집기는 구조를 강제하므로 잘못된 괄호나 유효하지 않은 유형으로 사양을 배포할 수 없습니다. 공유 Error 스키마 또는 공통 헤더와 같은 재사용 가능한 구성 요소는 몇 번의 클릭으로 사용할 수 있습니다.

디자인-우선 모드는 브랜치를 지원하므로 팀은 API 디자인의 별도 버전을 병렬로 작업하고 나중에 조정할 수 있습니다. 검토자는 원시 텍스트 대신 구조화된 차이점을 보게 되므로 YAML에 익숙하지 않은 사람들도 계약 변경 사항을 더 쉽게 읽을 수 있습니다.

단점: 추상화를 통해 작업해야 합니다. 이미 OpenAPI에 익숙하다면 양식이 머릿속에 있는 사양과 자신 사이에 불필요한 클릭을 추가하는 것처럼 느껴질 수 있습니다.

Apidog 사양-우선 모드

현재 베타 버전인 사양-우선 모드는 반대입니다. 양식 대신 IDE 스타일의 코드 편집기가 제공되며 YAML 또는 JSON으로 OpenAPI 또는 Swagger 사양을 직접 작성합니다. 이 모드는 API 정의를 다른 소스 파일처럼 Git에 보관하려는 팀을 위해 만들어졌습니다.

이 편집기는 코드 편집기의 편집기와 유사하게 작동합니다. OpenAPI 및 Swagger 스키마에 맞춰진 구문 강조, 인라인 유효성 검사 및 자동 완성을 제공합니다. 입력할 때 왼쪽 사이드바는 사양을 경로 및 구성 요소의 개요로 자동 구문 분석하므로 스크롤하지 않고도 큰 파일을 탐색할 수 있습니다. 동기화 표시기는 로컬 편집이 연결된 저장소와 동기화되어 있는지 보여줍니다.

주요 특징은 양방향 Git 동기화입니다. GitHub 또는 GitLab에 저장소를 연결하면 (Azure DevOps는 일반 Git 연결을 통해 작동) Apidog가 양방향으로 사양 파일을 동기화합니다. Apidog에서 편집한 다음 앱에서 바로 커밋하고 푸시합니다. 또는 코드 편집기에서 사양을 편집하고 거기서 푸시한 다음 변경 사항을 Apidog로 다시 가져옵니다. 사양 파일은 공유된 진실이며, 두 표면은 항상 일치합니다. 전체 설정은 사양-우선 모드 문서에서 확인할 수 있습니다.

이 모드는 API 계약을 다른 코드 아티팩트처럼 취급합니다. 즉, 풀 리퀘스트에서 검토되고, 이를 구현하는 서비스와 함께 버전 관리되며, 줄 단위로 차이점을 비교합니다. 팀이 이미 인프라 및 구성을 이런 방식으로 관리한다면, 코드형 API 사양에 대한 심층적인 분석에서 그 이유를 알아보십시오.

나란히 비교

두 모드 모두 동일한 OpenAPI를 생성하며 목업, 테스트 및 다운스트림 문서를 지원합니다. 사양을 작성하고 버전 관리하는 방식에서 차이가 있습니다.

어떤 팀이 어떤 것을 선택해야 하는가

기여자들이 모두 OpenAPI 전문가가 아니라면 디자인-우선 모드를 사용하십시오. 제품 관리자, QA, 주니어 엔지니어 모두 사양 구문을 배우지 않고도 엔드포인트를 추가하거나 검토할 수 있습니다. 또한 처음부터 새 API를 시작하고 형식에 신경 쓰지 않고 빠르게 구조를 만들고자 할 때 더 빠른 경로입니다.

사양-우선 모드는 사양이 서비스 코드 옆에 있는 Git 저장소에 이미 있거나 있어야 하는 경우에 사용하십시오. 풀 리퀘스트에서 API 변경 사항을 검토하고, CI에서 사양 린팅을 실행하거나, 도구 전반에 걸쳐 단일 정규 YAML 파일을 원하는 백엔드 팀은 익숙하게 사용할 것입니다. 양방향 동기화는 Apidog가 진실의 별도 사본이 아닌, 저장소가 보유한 동일한 파일의 창이 됨을 의미합니다.

실용적인 중간 경로: 많은 팀이 속도를 위해 디자인-우선 모드에서 새 엔드포인트를 설계한 다음, API가 성숙하고 Git 검토가 우선순위가 되면 사양-우선 모드로 전환합니다. 이 모드들은 경쟁 관계에 있는 제품이 아닙니다. 하나의 계약에 대한 두 가지 관점입니다.

모드 전환 방법

전환은 단일 토글로 이루어집니다. Apidog 프로젝트에서 API 모듈을 열고 왼쪽 하단 모서리에 있는 모드 전환기를 찾으십시오. 전환하면 동일한 계약이 다른 모드로 렌더링됩니다.

전환할 때 몇 가지 유의할 사항:

• 기본 사양은 공유되므로 엔드포인트, 스키마 및 예시가 그대로 유지됩니다. API를 재구축하는 것이 아니라 편집 표면을 변경하는 것입니다.
• 사양-우선 모드의 Git 동기화를 사용하려면 먼저 GitHub, GitLab 또는 Azure DevOps 저장소를 연결하십시오. 연결되면 동기화 표시기가 편집 내용이 커밋되고 푸시되었는지 여부를 알려줍니다.
• 사양-우선 모드는 베타 버전이므로, 프로덕션 계약에 의존하기 전에 동기화 동작을 확인할 수 있는 프로젝트에서 시도해 보십시오.

필요에 따라 앞뒤로 이동할 수 있으므로, 선택을 약속이 아닌 기본값으로 간주하십시오.

FAQ

사양-우선이 계약-우선과 동일한가요?

실제로 그렇습니다. "사양-우선"과 "계약-우선" 모두 구현 전에 API 사양을 작성한다는 것을 의미하며, 둘 다 사양을 진실의 원천으로 간주합니다. Apidog의 사양-우선 모드는 Git에 동기화된 수기 OpenAPI 또는 Swagger 파일이 계약인 계약-우선 워크플로우입니다.

사양-우선 모드는 GitLab 및 Azure DevOps와 함께 작동하나요?

네. 사양-우선 모드는 GitHub 및 GitLab과 직접적인 양방향 Git 동기화를 지원합니다. Azure DevOps는 일반 Git 연결을 통해 작동하므로 Azure에서 호스팅되는 저장소에도 사양 파일을 동기화할 수 있습니다.

디자인-우선에서 사양-우선으로 전환할 때 작업을 잃지 않고 전환할 수 있나요?

네. 두 모드 모두 동일한 기본 계약을 읽고 쓰므로 API 모듈의 왼쪽 하단에 있는 토글을 전환해도 엔드포인트, 스키마 및 예시가 손상되지 않습니다. 데이터를 바꾸는 것이 아니라 편집기를 교체하는 것입니다.

어떤 모드가 팀에 적합한지 잘 모르시겠다면, API 모듈을 열고 왼쪽 하단의 모드 토글을 사용하여 다음 엔드포인트를 두 가지 방법으로 모두 설계해 보세요. 어떤 방법을 사용하든 계약은 동일합니다. 팀이 이미 작업하는 방식과 일치하는 표면을 선택하십시오.