요약
디자인 우선 접근 방식은 구현 코드보다 먼저 API 사양을 작성하고, 이 사양이 모의(mock), 문서화, 테스트, 클라이언트 스텁 등 모든 후속 작업을 주도한다는 것을 의미합니다. 이러한 워크플로를 엔드투엔드로 지원하는 플랫폼을 선택하면 코드와 문서의 동기화를 유지하는 데 따르는 지속적인 마찰을 제거할 수 있습니다. 이 글에서는 디자인 우선 접근 방식을 설명하고, 완전한 디자인 우선 플랫폼인 Apidog를 통해 좋은 도구가 어떤 모습이어야 하는지 평가합니다.
ApidogApidog를 무료로 사용해 보세요
서론
대부분의 개발자는 코드 우선 방식으로 API를 구축하는 것을 배웁니다. 경로를 작성하고, 일부 주석을 추가하고, 생성기를 실행하면 문서가 나옵니다. 작동합니다. 더 이상 작동하지 않을 때까지는요.
문서는 계속해서 차이가 생깁니다. 주석은 최신 상태가 아닙니다. 새로운 엔지니어가 응답 형식을 변경했지만 데코레이터를 업데이트하는 것을 잊어버립니다. 6개월 후, 문서는 API가 문자열 배열을 반환한다고 말하지만 실제 응답은 `value` 필드가 있는 객체 배열을 반환합니다.
디자인 우선 방식은 이와는 반대입니다. 사양(spec)이 진실의 원천입니다. 코드, 문서, 모의(mock)는 모두 사양에서 파생됩니다. 사양이 변경되면 모든 것이 함께 변경됩니다. 모든 것이 사양에서 생성되었기 때문입니다.
이것은 이론적인 구별이 아닙니다. 디자인 우선 방식을 채택하는 팀은 통합 시 예상치 못한 문제를 덜 겪고, 더 빠른 프런트엔드 개발(모의가 첫날부터 사용 가능하기 때문)을 경험하며, 문서는 보조적인 산출물이 아니었기 때문에 정확하다고 보고합니다.
그러나 디자인 우선 방식은 사양 작성을 실용적일 만큼 빠르게 할 수 있는 도구가 필요합니다. 사양 도구에서 엔드포인트를 정의하는 데 20분이 걸리고 라우트 핸들러를 작성하는 데 5분이 걸린다면 아무도 사양 도구를 사용하지 않을 것입니다. 플랫폼은 디자인 우선 방식을 코드 우선 방식보다 느리게 만드는 것이 아니라 더 빠르게 만들어야 합니다.
실제로 디자인 우선 방식의 의미
디자인 우선은 기술이 아니라 워크플로입니다. 다음은 API 개발의 각 단계에서 어떻게 보이는지입니다.
코드 작성 전
API 디자인은 OpenAPI 사양으로 정의됩니다. 여기에는 다음이 포함됩니다.
- 모든 엔드포인트 경로 및 HTTP 메서드
- 요청 매개변수 정의 (경로, 쿼리, 헤더)
- POST/PUT/PATCH 엔드포인트에 대한 요청 본문 스키마
- 모든 상태 코드 (200, 400, 401, 422, 500)에 대한 응답 스키마
- 인증 요구 사항
- 필드 설명 및 예시
이 디자인 검토 단계에서 명명, 데이터 구조, 오류 처리 패턴과 같은 중요한 결정의 대부분이 이루어집니다.
개발 중
사양은 모의 서버에 게시됩니다. 프런트엔드 엔지니어는 모의 서버를 기반으로 구축하고, 백엔드 엔지니어는 사양을 요구 사항 문서로 간주하여 이를 구현합니다. 두 팀은 서로를 방해하지 않고 병렬로 작업합니다.
구현 후
자동화된 테스트는 실제 구현이 사양과 일치하는지 검증합니다. 계약에서 벗어나는 부분은 테스트에 실패합니다.
요구 사항 변경 시
사양이 먼저 업데이트됩니다. 두 팀 모두 변경 사항을 검토합니다. 모의는 자동으로 업데이트됩니다. 테스트는 업데이트된 사양을 따르지 않는 구현에 플래그를 지정합니다.
디자인 우선 플랫폼이 갖춰야 할 것
모든 API 도구가 디자인 우선 워크플로를 지원하는 것은 아닙니다. 다음은 디자인 우선을 지원하는 도구와 그렇지 않은 도구를 구별하는 요소입니다.
시각적 API 편집기
원시 YAML은 좋지 않은 디자인 매체입니다. 시각적 편집기를 사용하면 YAML 들여쓰기와 씨름하지 않고도 API 구조와 의미에 집중할 수 있습니다. 편집기는 유효한 OpenAPI를 생성하고, 스키마 재사용(컴포넌트)을 지원하며, 실시간으로 검증해야 합니다.
OpenAPI 유효성 검사
사양은 어떤 용도로든 사용되기 전에 유효한 OpenAPI여야 합니다. 인라인 유효성 검사는 코드 생성 또는 모의 생성 시점이 아니라 편집 중에 실수를 포착합니다.
사양 기반 자동 모의 생성
사양을 작성하면 모의가 생성됩니다. 추가 단계는 없습니다. 모의는 스키마의 필드 유형, 형식 및 제약 조건을 준수하는 데이터를 반환해야 합니다. 이것이 병렬 개발을 실용적으로 만드는 요소입니다.
실제 예시가 포함된 문서 미리보기
사양은 디자인 단계에서 이해관계자와 공유할 수 있는 읽기 쉬운 문서로 렌더링되어야 합니다. 비기술 팀원도 이를 읽고 피드백을 제공할 수 있어야 합니다.
팀 검토 워크플로
디자인 우선 방식은 사양 변경을 코드 변경과 동일하게 처리합니다: 누군가 변경을 제안하면 다른 사람들이 검토하고, 승인되거나 수정됩니다. 플랫폼은 비동기 댓글 및 변경 추적 기능을 필요로 합니다.
표준 OpenAPI로 내보내기
사양은 이식성이 있어야 합니다. 표준 OpenAPI로 내보내어 코드 생성기, API 게이트웨이, 테스트 프레임워크 등 모든 다운스트림 도구와 함께 사용할 수 있어야 합니다.
디자인 우선 플랫폼으로서의 Apidog
Apidog의 아키텍처는 사양을 주요 산출물로 중심으로 구축되어 있습니다. 디자인 탭, 모의 서버, 테스트 실행기 및 문서는 모두 동일한 기본 API 정의에 연결되어 있습니다.
시각적 OpenAPI 편집기
Apidog의 디자인 인터페이스는 폼 기반 편집을 사용합니다. 각 엔드포인트는 경로, 메서드, 매개변수, 요청 본문, 응답과 같은 구조화된 폼입니다. 스키마 필드는 유형 선택기, 설명 편집기, 유효성 검사 규칙 및 모의 주석으로 정의됩니다.
원하지 않는 한 YAML을 직접 작성할 필요가 없습니다. Apidog는 사양의 YAML 또는 JSON 표현을 보여주는 원시 뷰를 제공하며, 선호하는 경우 직접 편집할 수 있습니다. 시각적 뷰의 변경 사항은 원시 뷰와 동기화되며 그 반대도 마찬가지입니다.
스키마 컴포넌트는 일급 객체입니다. 컴포넌트 섹션에 `UserProfile` 스키마를 정의합니다. 모든 엔드포인트에서 `$ref`를 사용하여 참조합니다. 스키마를 한 번 변경하면 이를 참조하는 모든 엔드포인트에 변경 사항이 반영됩니다.
실시간 문서 미리보기
엔드포인트를 디자인하면 문서 뷰가 실시간으로 업데이트됩니다. 디자인 인터페이스를 벗어나지 않고도 게시된 문서에서 엔드포인트가 어떻게 표시될지 미리 볼 수 있습니다. 미리보기는 렌더링된 설명, 필드 유형 및 제약 조건이 있는 스키마 테이블, 예시 응답을 보여줍니다.
디자인 단계에서 제품 관리자나 프런트엔드 리더와 문서 링크를 공유하여 검토를 받으세요. 그들은 아무것도 설치할 필요가 없습니다.
Smart Mock: 사양에서 작동하는 모의로
Apidog 디자이너에서 새 엔드포인트를 저장하면 모의 서버가 즉시 준비됩니다. 모의 URL이 인터페이스에 나타납니다. 모의는 스키마를 기반으로 응답 데이터를 생성합니다.
- `format: email`이 있는 문자열 필드는 유효한 이메일 주소를 반환합니다.
- `minimum` 및 `maximum`이 있는 정수 필드는 범위 내의 값을 반환합니다.
- Enum 필드는 무작위로 선택된 enum 값을 반환합니다.
- 중첩된 객체와 배열은 중첩된 스키마 구조를 따릅니다.
- `$ref` 컴포넌트는 올바르게 해석되고 모의됩니다.
특정 시나리오에 대한 사용자 정의 모의 규칙을 설정할 수도 있습니다: 경로 매개변수가 `0`일 때 404를 반환하거나 특정 쿼리 매개변수 값에 대해 특정 페이로드를 반환합니다.
팀 검토 및 변경 추적
Apidog의 API 사양 변경 사항은 모든 워크스페이스 멤버에게 표시됩니다. 특정 엔드포인트나 필드에 댓글을 추가할 수 있습니다. 변경 기록은 누가, 무엇을, 언제 변경했는지 추적합니다.
디자인 우선 워크플로의 경우, 이는 사양 변경이 별도의 도구나 프로세스 없이 코드 변경과 동일한 검토 문화를 거친다는 것을 의미합니다.
디자인 우선 vs 코드 우선: 실제 장단점
디자인 우선이 항상 우월한 것은 아닙니다. 다음은 솔직한 비교입니다.
디자인 우선의 장점:
- 프런트엔드와 백엔드가 병렬로 작업할 수 있습니다 (주요 속도 이점).
- 문서가 파생물이 아닌 원본이기 때문에 정확합니다.
- 통합 문제는 통합 단계가 아닌 디자인 검토 단계에서 일찍 드러납니다.
- API 계약이 명시적이고 검증 가능합니다.
- API 변경 사항은 기본적으로 검토 프로세스를 거칩니다.
디자인 우선의 단점:
- 코드 작성 전에 사양을 정의하는 데 드는 초기 시간
- 사양 도구는 학습 곡선이 있습니다.
- 구현을 사양과 동기화 상태로 유지하기 위한 규율이 필요합니다.
- 초기에 과도하게 사양을 정의하면 도메인을 이해하기도 전에 결정에 갇힐 수 있습니다.
코드 우선의 장점:
- 작고 실험적인 프로젝트의 경우 초기 개발 속도가 빠릅니다.
- 빠르게 반복하는 단독 개발자의 경우 프로세스가 적습니다.
- 배울 사양 도구가 없습니다.
코드 우선의 단점:
- 문서는 항상 보조적인 산출물이며 점차 차이가 생기는 경향이 있습니다.
- 프런트엔드는 통합 작업을 시작하기 전에 백엔드를 기다려야 합니다.
- 계약이 암묵적이어서 파괴적인 변경을 감지하기 어렵습니다.
- API 리팩토링은 수동 문서 업데이트를 필요로 합니다.
API에 두 명 이상의 엔지니어가 작업하는 팀의 경우, 디자인 우선 방식이 일반적으로 더 나은 결과를 제공합니다. 사양 우선의 규율은 프런트엔드-백엔드 조정이 중요한 기능에서 가장 큰 효과를 발휘합니다.
디자인 우선 워크플로를 지원하는 도구
Apidog
완벽한 디자인 우선 플랫폼: 시각적 편집기, 즉각적인 모의 생성, 문서화, 테스트 및 팀 검토 기능을 하나의 도구에 통합. 무료 플랜은 모든 기능을 제공합니다. 강력한 모의 생성 기능은 진정한 차별점입니다.
Stoplight Studio
스타일 강화를 위한 Spectral 린팅 기능을 갖춘 동급 최고의 OpenAPI 편집기. 내장된 모의 서버나 테스트 실행기는 없습니다. 거버넌스 도구가 필요한 조직에 가장 적합합니다. 소규모 팀에게는 비용이 많이 듭니다.
SwaggerHub
성숙한 OpenAPI 편집 및 협업 플랫폼. 기업에서 널리 사용됩니다. 모의 기능이 제한적입니다. 테스트 기능은 없습니다. 이미 Swagger 생태계에 있는 사양 중심 조직에 적합합니다.
Postman (API 빌더 포함)
Postman에는 OpenAPI 사양을 생성하는 API 디자인 탭이 있지만, 디자인 및 컬렉션 워크플로가 분리된 느낌을 줍니다. 모의 서버는 사양에서 자동 생성되는 대신 컬렉션에서 수동 설정이 필요합니다. 일부 문서화 도구가 필요한 코드 우선 팀에 적합합니다.
Insomnia (문서 모드 포함)
Insomnia는 OpenAPI 사양 편집을 지원하고 기본적인 모의 기능을 제공합니다. 전용 디자인 우선 도구보다 정교함이 떨어집니다. 가벼운 옵션을 원하는 단독 개발자에게 적합합니다.
Apidog에서 디자인 우선 워크플로 설정하기
단계 1: 컬렉션이 아닌 사양으로 시작하기
새 프로젝트를 생성하고 디자인 탭을 엽니다. 요청 빌더에서 시작하려는 충동을 억제하십시오. 단일 요청을 보내기 전에 최소한 엔드포인트 경로, 메서드 및 응답 스키마를 정의하십시오.
단계 2: 공유 컴포넌트를 먼저 정의하기
엔드포인트를 추가하기 전에 재사용될 스키마(예: 오류 응답 형식, 페이지네이션 래퍼, 공통 엔티티 필드)를 정의하십시오. 이는 나중에 발생할 수 있는 불일치를 방지합니다.
단계 3: 모의 URL을 일찍 확보하기
엔드포인트가 저장되는 즉시 모의 URL을 복사하십시오. 이를 프런트엔드 엔지니어와 공유하십시오. 그들은 즉시 이를 기반으로 구축을 시작할 수 있습니다.
단계 4: 코드 작성 전에 문서를 검토하기
생성된 문서를 미리 보십시오. 문서에서 필드 설명이 명확하지 않다면 코드를 읽는 모든 사람에게도 명확하지 않을 것입니다. 사양에서 수정하십시오.
단계 5: 구현 시작 전에 사양을 잠그기
디자인 검토가 완료되고 댓글이 해결되면 해당 스프린트 동안 사양을 잠긴 것으로 간주하십시오. 사양 업데이트가 필요한 구현 변경 사항은 조용히 처리되는 것이 아니라 검토 프로세스를 거쳐야 합니다.
단계 6: CI에서 스키마 유효성 검사 테스트 실행하기
모든 CI 실행에서 Apidog의 테스트 스위트를 설정하여 응답 스키마를 검증하십시오. 이는 구현과 사양을 동기화 상태로 유지하는 자동화된 안전장치입니다.
자주 묻는 질문
디자인 우선은 REST API에만 해당되나요?아닙니다. 디자인 우선 원칙은 계약을 정의할 수 있는 모든 프로토콜에 적용됩니다: GraphQL의 스키마 우선, 프로토콜 버퍼를 사용하는 gRPC, 이벤트 기반 시스템을 위한 AsyncAPI. Apidog는 REST 및 GraphQL 디자인을 지원합니다. gRPC의 경우, 프로토 파일이 동일한 계약 우선 목적을 수행합니다.
개발 시작 전에 모든 엔드포인트를 정의해야 하나요?아닙니다. 기능 수준에서 디자인 우선을 채택할 수 있습니다: 코드베이스의 다른 부분이 코드 우선 방식이더라도, 구축하려는 기능에 대한 사양을 코드 작성 전에 정의하십시오. 점진적인 채택이 가능합니다.
애자일 스프린트에서 디자인 우선은 어떻게 작동하나요?스프린트 시작 시 디자인 세션은 해당 스프린트 기능에 대한 API 계약을 정의합니다. 스프린트 동안 프런트엔드와 백엔드가 병렬로 작업합니다. 사양 검토는 스프린트 계획의 일부가 됩니다.
구현이 원래 사양에서 벗어나야 한다면 어떻게 해야 하나요?그럴 수도 있습니다. 올바른 프로세스는 사양을 먼저 업데이트하고, 이해관계자(특히 프런트엔드)로부터 동의를 얻은 다음, 구현을 업데이트하는 것입니다. 이는 구현이 아닌 사양을 진실의 원천으로 유지합니다.
Apidog의 OpenAPI 내보내기를 통해 서버 스텁을 생성할 수 있나요?네. Apidog에서 사양을 OpenAPI 3.x로 내보낸 다음, 표준 코드 생성기를 사용하여 서버 스텁을 생성할 수 있습니다. openapi-generator는 50개 이상의 서버 언어 및 프레임워크를 지원합니다.
사양 버전 관리는 어떻게 하나요?Apidog는 프로젝트 내에서 변경 기록을 유지합니다. 병렬로 유지되는 주요 버전 변경 (v1과 v2 모두 활성화)의 경우, 별도의 프로젝트 또는 브랜치가 효과적입니다.
디자인 우선은 초기에 규율에 대한 작은 투자를 요구하지만, 통합 비용 감소 측면에서 상당한 이점을 제공합니다. 선택하는 플랫폼은 이러한 초기 투자를 최대한 낮게 만들 수 있어야 합니다. 사양 작성이 고통스럽다면 팀은 이를 건너뛸 것입니다. Apidog의 시각적 편집기, 즉각적인 모의 생성 및 문서 미리보기는 디자인 우선을 가장 미덕 있는 길이 아닌 가장 쉬운 길로 만듭니다.