DEV Community

Cover image for 디자인 우선 API 워크플로우를 위한 API 플랫폼
Rihpig
Rihpig

Posted on • Originally published at apidog.com

디자인 우선 API 워크플로우를 위한 API 플랫폼

요약

디자인 우선 접근 방식은 구현 코드보다 먼저 API 사양을 작성하고, 이 사양이 mock, 문서화, 테스트, 클라이언트 스텁 생성 등 후속 작업의 기준이 되도록 만드는 워크플로입니다. 사양을 단일 진실 공급원으로 두면 코드와 문서가 어긋나는 문제를 줄일 수 있습니다. 이 글에서는 디자인 우선 API 개발을 실제 팀 워크플로에 적용하는 방법과, Apidog 같은 플랫폼을 평가할 때 확인해야 할 기능을 정리합니다.

지금 Apidog를 사용해 보세요

Apidog

Apidog를 무료로 사용해 보세요

서론

많은 개발자는 코드 우선 방식으로 API를 만듭니다.

  1. 라우트를 작성합니다.
  2. 주석이나 데코레이터를 추가합니다.
  3. 문서 생성기를 실행합니다.
  4. OpenAPI 문서가 만들어집니다.

작은 프로젝트에서는 이 방식이 충분합니다. 하지만 팀 규모가 커지면 문제가 생깁니다.

예를 들어 문서에는 다음처럼 되어 있습니다.

[
  "apple",
  "banana"
]
Enter fullscreen mode Exit fullscreen mode

하지만 실제 API는 다음처럼 응답합니다.

[
  {
    "value": "apple"
  },
  {
    "value": "banana"
  }
]
Enter fullscreen mode Exit fullscreen mode

이런 차이는 보통 다음 상황에서 발생합니다.

  • 응답 형식을 바꿨지만 문서를 업데이트하지 않음
  • 주석 기반 문서가 실제 구현과 다름
  • 프런트엔드가 오래된 문서를 기준으로 개발함
  • QA 또는 외부 연동 팀이 실제 응답을 보고서야 문제를 발견함

디자인 우선 방식은 이 흐름을 뒤집습니다.

먼저 API 사양을 정의합니다. 그다음 코드, 문서, mock, 테스트가 모두 이 사양을 기준으로 움직입니다.

즉, 사양이 다음 작업의 입력값이 됩니다.

OpenAPI Spec
   ├── Mock Server
   ├── API Documentation
   ├── Backend Implementation
   ├── Contract Tests
   └── Client / Server Stub
Enter fullscreen mode Exit fullscreen mode

이 방식의 핵심은 “문서를 나중에 생성하는 것”이 아니라 “계약을 먼저 합의하는 것”입니다.

실제로 디자인 우선 방식의 의미

디자인 우선은 특정 기술이 아니라 API 개발 프로세스입니다. REST API에서는 보통 OpenAPI 사양이 중심이 됩니다.

코드 작성 전

먼저 OpenAPI 사양으로 API 계약을 정의합니다.

포함해야 할 항목은 다음과 같습니다.

  • 엔드포인트 경로
  • HTTP 메서드
  • path/query/header 파라미터
  • 요청 본문 스키마
  • 응답 스키마
  • 상태 코드별 응답
  • 인증 방식
  • 필드 설명
  • 예시 값

예를 들어 사용자 조회 API를 설계한다면 최소한 다음 구조를 먼저 정의합니다.

paths:
  /users/{id}:
    get:
      summary: 사용자 조회
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 사용자 정보
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '404':
          description: 사용자를 찾을 수 없음
Enter fullscreen mode Exit fullscreen mode

그리고 공통 스키마는 components에 둡니다.

components:
  schemas:
    UserProfile:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          example: usr_123
        email:
          type: string
          format: email
          example: user@example.com
        name:
          type: string
          example: Jane Doe
Enter fullscreen mode Exit fullscreen mode

이 단계에서 다음 결정을 미리 합의합니다.

  • 필드 이름은 snake_case인가 camelCase인가
  • 오류 응답 형식은 어떻게 통일할 것인가
  • pagination은 어떤 구조를 사용할 것인가
  • nullable 필드는 어떻게 표현할 것인가
  • enum 값은 어디까지 허용할 것인가

개발 중

사양이 준비되면 mock 서버를 먼저 사용할 수 있습니다.

프런트엔드 팀은 실제 백엔드 구현을 기다리지 않고 mock API를 기준으로 화면과 상태 관리를 구현합니다.

const response = await fetch('https://mock.example.com/users/usr_123');
const user = await response.json();

console.log(user.email);
Enter fullscreen mode Exit fullscreen mode

백엔드 팀은 같은 사양을 요구사항 문서처럼 사용해 구현합니다.

app.get('/users/:id', async (req, res) => {
  const user = await userService.findById(req.params.id);

  if (!user) {
    return res.status(404).json({
      code: 'USER_NOT_FOUND',
      message: '사용자를 찾을 수 없습니다.'
    });
  }

  return res.json(user);
});
Enter fullscreen mode Exit fullscreen mode

이렇게 하면 프런트엔드와 백엔드가 같은 계약을 기준으로 병렬 작업할 수 있습니다.

구현 후

구현이 끝나면 실제 API 응답이 사양과 일치하는지 검증합니다.

예를 들어 응답 스키마에는 email이 필수인데 실제 응답에서 누락된다면 테스트가 실패해야 합니다.

{
  "id": "usr_123",
  "name": "Jane Doe"
}
Enter fullscreen mode Exit fullscreen mode

이 응답은 다음 스키마를 만족하지 않습니다.

required:
  - id
  - email
Enter fullscreen mode Exit fullscreen mode

디자인 우선 워크플로에서는 이런 불일치를 수동 리뷰가 아니라 계약 테스트로 잡아야 합니다.

요구 사항 변경 시

요구 사항이 바뀌면 구현부터 수정하지 않습니다.

올바른 순서는 다음과 같습니다.

  1. OpenAPI 사양 수정
  2. 변경 사항 리뷰
  3. mock 및 문서 갱신
  4. 프런트엔드/백엔드 영향 확인
  5. 구현 수정
  6. 계약 테스트 실행

즉, 변경도 사양을 기준으로 관리합니다.

디자인 우선 플랫폼이 갖춰야 할 것

모든 API 도구가 디자인 우선 워크플로에 적합한 것은 아닙니다. 다음 기능을 확인해야 합니다.

1. 시각적 API 편집기

OpenAPI YAML을 직접 작성할 수는 있지만, 모든 팀원이 YAML 기반으로 설계하는 것은 비효율적입니다.

좋은 디자인 우선 도구는 다음을 제공해야 합니다.

  • 엔드포인트 생성 UI
  • path/query/header 파라미터 편집
  • 요청/응답 스키마 편집
  • enum, required, format, min/max 같은 제약 조건 설정
  • OpenAPI 유효성 검사
  • 재사용 가능한 schema component 관리

예를 들어 UserProfile 스키마를 한 번 정의하고 여러 API에서 재사용할 수 있어야 합니다.

schema:
  $ref: '#/components/schemas/UserProfile'
Enter fullscreen mode Exit fullscreen mode

2. OpenAPI 유효성 검사

사양은 downstream 도구에서 사용되기 전에 유효해야 합니다.

다음과 같은 문제를 편집 중에 바로 잡을 수 있어야 합니다.

  • 잘못된 $ref
  • 누락된 response description
  • 잘못된 schema type
  • 필수 필드와 properties 불일치
  • 유효하지 않은 OpenAPI 구조

유효성 검사가 늦게 실행되면 mock 생성, 문서 생성, 코드 생성 단계에서 문제가 터집니다. 디자인 단계에서 바로 피드백을 받아야 합니다.

3. 사양 기반 자동 mock 생성

디자인 우선의 실질적인 장점은 mock 서버입니다.

사양을 저장하면 별도 구현 없이 mock API가 준비되어야 합니다.

예를 들어 스키마가 다음과 같다면:

properties:
  email:
    type: string
    format: email
  age:
    type: integer
    minimum: 18
    maximum: 65
  role:
    type: string
    enum:
      - admin
      - user
Enter fullscreen mode Exit fullscreen mode

mock 응답은 다음 조건을 만족해야 합니다.

  • email은 이메일 형식
  • age는 18~65 범위의 정수
  • role은 admin 또는 user
  • 중첩 객체와 배열도 스키마 구조를 따름
  • $ref로 연결된 컴포넌트도 해석됨

4. 실제 예시가 포함된 문서 미리보기

사양은 개발자만 보는 파일이 아닙니다. 제품 관리자, QA, 프런트엔드 리드, 외부 파트너도 읽을 수 있어야 합니다.

따라서 도구는 다음을 제공해야 합니다.

  • 읽기 쉬운 문서 페이지
  • 엔드포인트별 설명
  • 요청/응답 예시
  • 필드 설명
  • 인증 정보
  • 상태 코드별 응답

문서 미리보기는 디자인 검토 단계에서 특히 중요합니다. 문서로 읽었을 때 이해가 안 된다면, 실제 연동 단계에서도 문제가 생길 가능성이 높습니다.

5. 팀 검토 워크플로

API 사양 변경은 코드 변경과 동일하게 리뷰되어야 합니다.

필요한 기능은 다음과 같습니다.

  • 엔드포인트 단위 댓글
  • 필드 단위 피드백
  • 변경 기록
  • 누가 무엇을 언제 바꿨는지 추적
  • 비동기 리뷰

예를 들어 userId를 id로 바꾸는 변경은 단순한 이름 변경이 아닐 수 있습니다. 클라이언트 코드, 문서, 테스트, mock 모두에 영향을 줍니다.

6. 표준 OpenAPI 내보내기

사양은 특정 도구에 갇히면 안 됩니다.

OpenAPI 3.x 형식으로 내보낼 수 있어야 다음 도구와 함께 사용할 수 있습니다.

  • 코드 생성기
  • API Gateway
  • 테스트 프레임워크
  • CI 파이프라인
  • 문서 생성기
  • SDK 생성 도구

예를 들어 openapi-generator를 사용하면 OpenAPI 사양에서 서버 스텁이나 클라이언트 SDK를 생성할 수 있습니다.

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./generated/client
Enter fullscreen mode Exit fullscreen mode

디자인 우선 플랫폼으로서의 Apidog

Apidog의 구조는 API 정의를 중심으로 디자인, mock, 문서, 테스트를 연결합니다.

디자인 탭에서 정의한 API는 mock 서버, 테스트 실행기, 문서에 같은 기준으로 반영됩니다.

시각적 OpenAPI 편집기

Apidog의 디자인 인터페이스는 폼 기반 편집 방식을 사용합니다.

각 엔드포인트에서 다음 항목을 구조화해서 정의할 수 있습니다.

  • 경로
  • HTTP 메서드
  • 파라미터
  • 요청 본문
  • 응답
  • 스키마 필드
  • 설명
  • 유효성 검사 규칙
  • mock 관련 설정

YAML을 직접 작성하지 않아도 OpenAPI 사양을 구성할 수 있습니다. 필요한 경우 YAML 또는 JSON 원시 뷰에서 직접 편집할 수도 있습니다.

시각적 뷰와 원시 뷰는 동기화됩니다.

실무에서는 다음 순서로 설계하는 것이 좋습니다.

  1. 공통 error response schema 생성
  2. 공통 pagination schema 생성
  3. 주요 entity schema 생성
  4. 엔드포인트별 request/response 연결
  5. 예시 값 추가
  6. 문서 미리보기로 확인

예를 들어 공통 오류 응답은 다음처럼 재사용할 수 있습니다.

components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: USER_NOT_FOUND
        message:
          type: string
          example: 사용자를 찾을 수 없습니다.
Enter fullscreen mode Exit fullscreen mode

각 엔드포인트에서는 $ref로 참조합니다.

responses:
  '404':
    description: 리소스를 찾을 수 없음
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/ErrorResponse'
Enter fullscreen mode Exit fullscreen mode

실시간 문서 미리보기

Apidog에서 엔드포인트를 설계하면 문서 뷰가 함께 업데이트됩니다.

문서 미리보기에서 확인할 항목은 다음과 같습니다.

  • summary와 description이 충분한가
  • 요청 예시가 실제 사용 사례와 맞는가
  • 응답 필드 설명이 모호하지 않은가
  • 에러 응답이 상태 코드별로 정의되어 있는가
  • 인증 요구 사항이 명확한가

디자인 단계에서 문서 링크를 제품 관리자나 프런트엔드 리더에게 공유해 리뷰를 받을 수 있습니다. 별도 설치 없이 문서 기준으로 피드백을 받을 수 있다는 점이 중요합니다.

Smart Mock: 사양에서 동작하는 mock으로

Apidog에서 새 엔드포인트를 저장하면 mock 서버를 바로 사용할 수 있습니다.

mock은 스키마를 기준으로 응답 데이터를 생성합니다.

예를 들어 다음 조건이 반영됩니다.

  • format: email인 문자열 필드는 이메일 형식으로 반환
  • minimum, maximum이 있는 숫자 필드는 범위 내 값 반환
  • enum 필드는 enum 값 중 하나 반환
  • 중첩 객체와 배열은 스키마 구조를 따름
  • $ref 컴포넌트도 해석됨

실무에서는 mock URL을 가능한 한 빨리 공유하는 것이 좋습니다.

// 프런트엔드에서 mock API 사용 예시
const res = await fetch('https://mock-api.example.com/users/usr_123');
const user = await res.json();

renderUserProfile(user);
Enter fullscreen mode Exit fullscreen mode

특정 시나리오도 mock으로 표현할 수 있습니다.

예를 들어 다음과 같은 케이스입니다.

  • path parameter가 0이면 404 반환
  • 특정 query parameter 값에 대해 빈 배열 반환
  • 특정 상태 코드 응답을 테스트
  • 에러 메시지 UI 확인

이렇게 하면 백엔드 구현이 끝나기 전에도 프런트엔드의 성공/실패 흐름을 테스트할 수 있습니다.

팀 검토 및 변경 추적

Apidog에서는 API 사양 변경 사항을 워크스페이스 멤버가 확인할 수 있습니다.

디자인 우선 워크플로에서는 다음 규칙을 두는 것이 좋습니다.

  • 사양 변경은 리뷰 없이 merge하지 않는다
  • response schema 변경은 프런트엔드 담당자 확인을 받는다
  • error code 추가/삭제는 QA와 공유한다
  • breaking change는 별도 버전 또는 명확한 마이그레이션 계획을 둔다

이렇게 하면 API 변경이 개인의 로컬 구현에 묻히지 않고 팀 단위로 관리됩니다.

디자인 우선 vs 코드 우선: 실제 장단점

디자인 우선이 항상 정답은 아닙니다. 프로젝트 성격에 따라 선택해야 합니다.

디자인 우선의 장점

  • 프런트엔드와 백엔드가 병렬로 작업할 수 있음
  • 문서가 실제 계약이므로 정확도가 높음
  • 통합 문제가 개발 후반이 아니라 설계 단계에서 드러남
  • API 계약이 명시적이고 검증 가능함
  • 변경 사항이 리뷰 프로세스를 거치기 쉬움
  • mock 서버를 통해 초기 UI 개발 속도가 빨라짐

디자인 우선의 단점

  • 코드 작성 전 사양을 정의하는 초기 시간이 필요함
  • OpenAPI와 도구 사용법을 익혀야 함
  • 구현과 사양을 계속 동기화하는 규율이 필요함
  • 도메인을 충분히 모르는 상태에서 과도하게 설계하면 변경 비용이 커질 수 있음

코드 우선의 장점

  • 작은 실험 프로젝트에서는 시작이 빠름
  • 단독 개발자가 빠르게 프로토타입을 만들 때 적합함
  • 별도 사양 도구 학습이 필요 없음

코드 우선의 단점

  • 문서가 구현의 부산물이 되어 drift가 생기기 쉬움
  • 프런트엔드는 백엔드 구현을 기다려야 할 수 있음
  • API 계약이 암묵적이라 breaking change를 감지하기 어려움
  • 리팩터링 시 문서 업데이트가 누락되기 쉬움

실무 기준으로는 다음처럼 판단할 수 있습니다.

상황 추천 방식
단독 개발자의 빠른 프로토타입 코드 우선
내부용 작은 스크립트성 API 코드 우선
프런트엔드/백엔드가 분리된 팀 디자인 우선
외부 파트너가 사용하는 API 디자인 우선
모바일 앱과 서버가 동시에 개발되는 경우 디자인 우선
장기 유지보수가 필요한 공개 API 디자인 우선

API에 두 명 이상의 엔지니어가 관여한다면 디자인 우선 방식이 대체로 더 안정적입니다.

디자인 우선 워크플로를 지원하는 도구

Apidog

Apidog는 시각적 편집기, mock 생성, 문서화, 테스트, 팀 검토 기능을 하나의 도구에서 제공합니다.

디자인 우선 워크플로에서 특히 중요한 부분은 사양을 만들면 mock과 문서가 같은 정의에서 연결된다는 점입니다.

Stoplight Studio

Stoplight Studio는 OpenAPI 편집과 Spectral 기반 린팅에 강점이 있습니다.

API 스타일 가이드와 거버넌스를 중요하게 보는 조직에 적합합니다. 다만 내장 mock 서버나 테스트 실행기까지 하나의 흐름으로 제공하는 도구를 원하는 경우에는 추가 구성이 필요할 수 있습니다.

SwaggerHub

SwaggerHub는 성숙한 OpenAPI 편집 및 협업 플랫폼입니다.

이미 Swagger 생태계를 사용하는 조직에서 사양 중심 API 관리를 할 때 적합합니다. mock이나 테스트 측면에서는 별도 도구와 함께 사용하는 경우가 많습니다.

Postman API Builder

Postman은 API 디자인 기능을 제공하며 OpenAPI 사양을 다룰 수 있습니다.

다만 디자인 워크플로와 컬렉션 기반 요청 실행 워크플로가 분리되어 느껴질 수 있습니다. 코드 우선 팀이 문서화와 테스트를 점진적으로 강화할 때 적합합니다.

Insomnia

Insomnia는 OpenAPI 사양 편집과 기본적인 mock 기능을 제공합니다.

가벼운 도구를 원하는 개인 개발자나 소규모 프로젝트에서 사용할 수 있습니다.

Apidog에서 디자인 우선 워크플로 설정하기

다음은 Apidog를 사용해 디자인 우선 API 개발을 시작하는 실무 절차입니다.

단계 1: 컬렉션이 아니라 사양으로 시작하기

새 프로젝트를 만들고 디자인 탭에서 시작합니다.

바로 요청을 보내기 전에 최소한 다음을 정의합니다.

  • 엔드포인트 경로
  • HTTP 메서드
  • 성공 응답 스키마
  • 주요 에러 응답 스키마

예를 들어 사용자 목록 API라면 먼저 계약을 정의합니다.

GET /users
Enter fullscreen mode Exit fullscreen mode

응답은 다음처럼 정합니다.

{
  "items": [
    {
      "id": "usr_123",
      "email": "user@example.com",
      "name": "Jane Doe"
    }
  ],
  "total": 1
}
Enter fullscreen mode Exit fullscreen mode

단계 2: 공유 컴포넌트를 먼저 정의하기

엔드포인트를 많이 만들기 전에 공통 스키마를 정의합니다.

추천 컴포넌트는 다음과 같습니다.

  • ErrorResponse
  • PaginationMeta
  • PaginatedResponse
  • UserProfile
  • AuditFields
  • 공통 enum

예시:

components:
  schemas:
    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
          example: 1
        pageSize:
          type: integer
          example: 20
        total:
          type: integer
          example: 100
Enter fullscreen mode Exit fullscreen mode

공유 컴포넌트를 먼저 만들면 엔드포인트마다 비슷하지만 다른 응답 형식이 생기는 것을 줄일 수 있습니다.

단계 3: mock URL을 일찍 확보하기

엔드포인트를 저장한 뒤 mock URL을 바로 공유합니다.

프런트엔드 팀은 다음 작업을 즉시 시작할 수 있습니다.

  • API client 함수 작성
  • 로딩/성공/실패 상태 구현
  • UI 컴포넌트 렌더링
  • 빈 데이터 상태 처리
  • 에러 메시지 처리

예시:

export async function getUsers() {
  const res = await fetch(`${API_BASE_URL}/users`);

  if (!res.ok) {
    throw new Error('사용자 목록을 불러오지 못했습니다.');
  }

  return res.json();
}
Enter fullscreen mode Exit fullscreen mode

초기에는 API_BASE_URL을 mock URL로 두고, 백엔드 구현이 준비되면 실제 API URL로 바꿉니다.

단계 4: 코드 작성 전에 문서를 검토하기

생성된 문서를 미리 보고 다음 질문을 확인합니다.

  • 이 API가 어떤 문제를 해결하는지 명확한가?
  • 필수 필드와 선택 필드가 구분되어 있는가?
  • 예시 응답이 실제 화면 요구사항과 맞는가?
  • 에러 응답이 충분히 정의되어 있는가?
  • 인증 방식이 명확한가?

문서에서 이해하기 어려운 API는 구현 후에도 연동하기 어렵습니다. 코드 작성 전에 사양에서 수정하는 편이 비용이 낮습니다.

단계 5: 구현 시작 전에 사양을 잠그기

디자인 리뷰가 끝나면 해당 스프린트 범위에서는 사양을 기준선으로 삼습니다.

권장 규칙은 다음과 같습니다.

  • 사양 변경은 댓글 또는 리뷰를 거친다
  • breaking change는 프런트엔드와 백엔드가 함께 승인한다
  • 구현 중 발견한 변경 필요 사항도 먼저 사양에 반영한다
  • 문서와 mock이 업데이트된 뒤 구현을 수정한다

이 규칙이 없으면 디자인 우선은 쉽게 코드 우선으로 되돌아갑니다.

단계 6: CI에서 스키마 유효성 검사 테스트 실행하기

구현이 사양과 계속 일치하도록 CI에서 테스트를 실행합니다.

검증해야 할 항목은 다음과 같습니다.

  • 실제 응답 status code
  • response body schema
  • required field 존재 여부
  • field type
  • enum 값
  • error response 구조

예를 들어 테스트 흐름은 다음과 같이 구성할 수 있습니다.

1. 테스트 환경에 API 서버 배포
2. Apidog 테스트 실행
3. 응답이 OpenAPI 스키마와 일치하는지 검증
4. 실패 시 CI 실패 처리
Enter fullscreen mode Exit fullscreen mode

이 단계가 있어야 디자인 우선 워크플로가 문서 작성에서 끝나지 않고 실제 품질 관리로 이어집니다.

자주 묻는 질문

디자인 우선은 REST API에만 해당되나요?

아닙니다.

디자인 우선 원칙은 계약을 먼저 정의할 수 있는 여러 방식에 적용됩니다.

  • REST: OpenAPI
  • GraphQL: schema-first
  • gRPC: Protocol Buffers
  • Event-driven system: AsyncAPI

Apidog는 REST 및 GraphQL 디자인을 지원합니다. gRPC에서는 proto 파일이 유사한 계약 우선 역할을 합니다.

개발 시작 전에 모든 엔드포인트를 정의해야 하나요?

아닙니다.

기능 단위로 점진적으로 적용할 수 있습니다.

예를 들어 기존 코드베이스는 코드 우선으로 유지하더라도, 새로 만드는 결제 기능만 다음 순서로 진행할 수 있습니다.

  1. 결제 API 사양 작성
  2. mock 공유
  3. 프런트엔드/백엔드 병렬 개발
  4. 계약 테스트 추가

전체 조직이 한 번에 전환하지 않아도 됩니다.

애자일 스프린트에서 디자인 우선은 어떻게 작동하나요?

스프린트 초반에 API 디자인 세션을 둡니다.

권장 흐름은 다음과 같습니다.

  1. 스프린트 계획에서 API가 필요한 기능 확인
  2. API 사양 초안 작성
  3. 프런트엔드/백엔드/QA 리뷰
  4. mock URL 공유
  5. 병렬 구현
  6. 스프린트 중 변경 사항은 사양부터 업데이트

사양 리뷰가 스프린트 계획의 일부가 되는 것이 핵심입니다.

구현이 원래 사양에서 벗어나야 한다면 어떻게 해야 하나요?

먼저 사양을 업데이트해야 합니다.

올바른 순서는 다음과 같습니다.

  1. 사양 변경 제안
  2. 영향 받는 팀 리뷰
  3. mock 및 문서 업데이트
  4. 구현 수정
  5. 계약 테스트 실행

구현이 사양을 조용히 앞서가면 다시 코드 우선 방식이 됩니다.

Apidog의 OpenAPI 내보내기로 서버 스텁을 생성할 수 있나요?

네.

Apidog에서 OpenAPI 3.x 형식으로 사양을 내보낸 뒤 표준 코드 생성기를 사용할 수 있습니다.

예를 들어 openapi-generator를 사용할 수 있습니다.

openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o ./generated/server
Enter fullscreen mode Exit fullscreen mode

또는 TypeScript 클라이언트를 생성할 수도 있습니다.

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./generated/client
Enter fullscreen mode Exit fullscreen mode

사양 버전 관리는 어떻게 하나요?

Apidog는 프로젝트 내 변경 기록을 유지합니다.

주요 버전이 병렬로 유지되어야 한다면 다음 방식이 효과적입니다.

  • v1과 v2를 별도 프로젝트로 관리
  • 브랜치 또는 별도 사양 파일로 관리
  • breaking change는 명확히 문서화
  • deprecated endpoint는 제거 일정 표시

예를 들어 외부 클라이언트가 아직 v1을 사용한다면 v2 사양을 별도로 관리하는 편이 안전합니다.

마무리

디자인 우선은 API 개발 초기에 약간의 규율을 요구합니다. 하지만 그 대가로 통합 비용, 문서 불일치, 프런트엔드 대기 시간을 줄일 수 있습니다.

핵심은 다음입니다.

  • 사양을 먼저 작성한다
  • mock을 즉시 공유한다
  • 문서를 디자인 리뷰에 사용한다
  • 구현은 사양을 따른다
  • CI에서 계약을 검증한다

도구는 이 과정을 어렵게 만들면 안 됩니다. 사양 작성이 번거로우면 팀은 결국 건너뛰게 됩니다.

Apidog의 시각적 편집기, 즉각적인 mock 생성, 문서 미리보기, 테스트 기능은 디자인 우선 워크플로를 더 쉽게 적용할 수 있게 해줍니다.

Top comments (0)