OpenAPI 3.2 vs 3.1 vs 3.0 변경 사항 비교

요약 (TL;DR)

OpenAPI 3.1은 완전한 JSON 스키마 호환성, 웹훅, 판별자(discriminator) 개선 사항을 추가했습니다. OpenAPI 3.2는 QUERY 메서드 지원, 향상된 예제, 개선된 보안 정의를 추가했습니다. Modern PetstoreAPI는 프로덕션에 즉시 사용 가능한 예시로 최신 기능을 모두 보여주기 위해 OpenAPI 3.2를 사용합니다.

소개

OpenAPI 사양을 작성하고 있습니다. OpenAPI 3.0, 3.1, 3.2에 대한 참조를 보게 됩니다. 차이점은 무엇일까요? 업그레이드해야 할까요? 사용하는 도구가 새 버전을 지원할까요?

OpenAPI는 3.0부터 3.2까지 크게 발전했습니다. 각 버전은 API 사양을 더 강력하고 정확하게 만드는 기능을 추가합니다. 하지만 모든 도구가 최신 버전을 지원하는 것은 아니므로 호환성 문제가 발생합니다.

오래된 Swagger Petstore는 OpenAPI 2.0 (Swagger 사양)을 사용합니다. Modern PetstoreAPI는 OpenAPI 3.2를 사용하여 모든 새로운 기능을 프로덕션에 즉시 사용 가능한 예시로 보여줍니다.

이 가이드에서는 각 OpenAPI 버전에서 무엇이 변경되었는지, 올바른 버전을 선택하는 방법, 그리고 Modern PetstoreAPI가 OpenAPI 3.2 기능을 어떻게 시연하는지 알아봅니다.

OpenAPI 3.0 기준

OpenAPI 3.0 (2017년 7월 출시)은 Swagger 2.0에서 대폭 업그레이드되었습니다.

주요 기능

1. 여러 서버

servers:
  - url: https://api.petstoreapi.com/v1
    description: Production
  - url: https://staging.petstoreapi.com/v1
    description: Staging

Swagger 2.0은 하나의 호스트만 지원했습니다.

2. 요청 본문(request body) 객체

requestBody:
  required: true
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'

Swagger 2.0의 body 매개변수보다 명확합니다.

3. 재사용성을 위한 컴포넌트(Components)

components:
  schemas:
    Pet:
      type: object
  responses:
    NotFound:
      description: Resource not found
  parameters:
    PetId:
      name: petId
      in: path

Swagger 2.0의 definitions보다 구성이 좋습니다.

4. 콜백(Callbacks)

비동기 콜백(웹훅) 정의:

callbacks:
  orderUpdate:
    '{$request.body#/callbackUrl}':
      post:
        requestBody:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderUpdate'

5. 링크(Links)

작업 간의 관계 정의:

links:
  GetPetByPetId:
    operationId: getPetById
    parameters:
      petId: '$response.body#/id'

제한 사항

1. JSON 스키마 비호환성

OpenAPI 3.0은 JSON 스키마 초안 5의 하위 집합을 사용했으며, 완전한 JSON 스키마가 아니었습니다. 이로 인해 유효성 검사 문제가 발생했습니다.

2. 웹훅 객체 없음

웹훅은 콜백으로 정의되어 혼란을 야기했습니다.

3. 제한된 판별자(discriminator)

다형성(polymorphism) 지원이 기본적이었습니다.

4. null 타입 없음

type: null을 직접 지정할 수 없었습니다.

OpenAPI 3.1 주요 변경 사항

OpenAPI 3.1 (2021년 2월 출시)은 JSON 스키마 정렬에 중점을 두었습니다.

1. 완전한 JSON 스키마 2020-12 호환성

가장 큰 변화: OpenAPI 3.1 스키마는 유효한 JSON 스키마 2020-12입니다.

이전 (OpenAPI 3.0):

type: string
nullable: true  # OpenAPI-specific

이후 (OpenAPI 3.1):

type: [string, "null"]  # 표준 JSON 스키마

장점:

• 모든 JSON 스키마 유효성 검사기를 사용할 수 있습니다.
• OpenAPI와 다른 도구 간에 스키마를 공유할 수 있습니다.
• 완전한 JSON 스키마 기능에 액세스할 수 있습니다.

2. 웹훅(Webhooks) 객체

이전 (OpenAPI 3.0):

# 콜백으로 정의된 웹훅 (혼란스러움)
paths:
  /subscribe:
    post:
      callbacks:
        orderUpdate:
          # 웹훅 정의

이후 (OpenAPI 3.1):

webhooks:
  orderUpdate:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderUpdate'

API 엔드포인트와 웹훅 간의 명확한 분리.

3. 개선된 판별자(Discriminator)

더 나은 다형성 지원:

oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
discriminator:
  propertyName: petType
  mapping:
    cat: '#/components/schemas/Cat'
    dog: '#/components/schemas/Dog'

4. Info 객체 라이선스 식별자

info:
  license:
    name: MIT
    identifier: MIT  # SPDX 식별자

5. PathItem $ref

전체 경로 항목 참조:

paths:
  /pets:
    $ref: '#/components/pathItems/PetsCollection'

호환성이 깨지는 변경 사항

1. nullable 제거됨

대신 type: [string, "null"]을 사용합니다.

2. exclusiveMinimum/exclusiveMaximum 변경됨

이제 숫자 대신 부울(boolean)입니다.

3. example vs examples

더 엄격한 유효성 검사.

OpenAPI 3.2 최신 기능

OpenAPI 3.2 (출시 예정, 초안 사용 가능)는 최신 API 패턴을 추가합니다.

1. QUERY 메서드 지원

복잡한 검색을 위한 HTTP QUERY 메서드:

paths:
  /pets/search:
    query:  # 새로운 메서드
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: object
                sort:
                  type: array
      responses:
        '200':
          description: Search results

Modern PetstoreAPI는 복잡한 반려동물 검색을 위해 QUERY를 사용합니다.

2. 개선된 예제

메타데이터가 포함된 여러 예제:

examples:
  availableCat:
    summary: Available cat
    description: A cat available for adoption
    value:
      id: "019b4132-70aa-764f-b315-e2803d882a24"
      name: "Fluffy"
      species: "CAT"
      status: "AVAILABLE"
  adoptedDog:
    summary: Adopted dog
    value:
      id: "019b4127-54d5-76d9-b626-0d4c7bfce5b6"
      name: "Buddy"
      species: "DOG"
      status: "ADOPTED"

3. 향상된 보안 정의

더 나은 OAuth 2.0 지원:

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://petstoreapi.com/oauth/authorize
          tokenUrl: https://petstoreapi.com/oauth/token
          refreshUrl: https://petstoreapi.com/oauth/refresh
          scopes:
            pets:read: Read pets
            pets:write: Create and update pets
            orders:read: Read orders

4. 개선된 판별자(Discriminator) 매핑

더 유연한 다형성:

discriminator:
  propertyName: type
  mapping:
    cat: Cat
    dog: Dog
    bird: '#/components/schemas/Bird'  # 로컬 및 $ref 혼합 가능

5. 더 나은 비권장(Deprecation) 지원

특정 필드 비권장:

properties:
  oldField:
    type: string
    deprecated: true
    description: Use newField instead
  newField:
    type: string

Modern PetstoreAPI가 OpenAPI 3.2를 사용하는 방법

Modern PetstoreAPI는 모든 OpenAPI 3.2 기능을 선보입니다.

1. 전체 사양

전체 OpenAPI 3.2 사양은 다음에서 사용할 수 있습니다:

https://petstoreapi.com/openapi.json

2. 복잡한 검색을 위한 QUERY 메서드

/pets/search:
  query:
    summary: Search pets with complex criteria
    requestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PetSearchQuery'

3. 웹훅

webhooks:
  petStatusChanged:
    post:
      summary: Pet status changed
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PetStatusWebhook'

4. 다형적 스키마

Pet:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Bird'
  discriminator:
    propertyName: species

5. 포괄적인 예제

모든 엔드포인트는 다양한 시나리오를 보여주는 여러 예제를 포함합니다.

6. RFC 9457 오류 응답

responses:
  '400':
    description: Bad Request
    content:
      application/problem+json:
        schema:
          $ref: '#/components/schemas/ProblemDetails'

모든 기능을 보려면 전체 OpenAPI 사양을 참조하십시오.

마이그레이션 가이드

3.0에서 3.1로

1. nullable 교체:

# 이전
type: string
nullable: true

# 이후
type: [string, "null"]

2. exclusiveMinimum/exclusiveMaximum 업데이트:

# 이전
minimum: 0
exclusiveMinimum: true

# 이후
minimum: 0
exclusiveMinimum: 0

3. 웹훅 이동:

# 이전
paths:
  /subscribe:
    callbacks:
      # 웹훅

# 이후
webhooks:
  # 웹훅

3.1에서 3.2로

1. 적절한 곳에 QUERY 메서드 추가:

/pets/search:
  query:  # 3.2의 새로운 기능
    # 복잡한 검색

2. 예제 향상:

examples:
  example1:
    summary: Description
    value: {...}

3. 보안 정의 업데이트:

OAuth 흐름에 refreshUrl 추가.

Apidog로 OpenAPI 사양 테스트

Apidog는 모든 OpenAPI 버전을 지원합니다.

OpenAPI 사양 가져오기

1. Apidog를 엽니다
2. "가져오기"를 클릭합니다
3. "OpenAPI 3.x"를 선택합니다
4. URL을 붙여넣거나 파일을 업로드합니다
5. Apidog가 유효성을 검사하고 가져옵니다

사양 유효성 검사

Apidog가 확인하는 사항:

• 스키마 유효성
• 참조 무결성
• 예제 정확성
• 보안 정의 완전성

API 구현 테스트

사양에서 테스트 케이스 생성:

• 요청 유효성 검사
• 응답 유효성 검사
• 상태 코드 확인
• 스키마 준수

버전 비교

여러 버전을 가져와 비교:

• 호환성이 깨지는 변경 사항
• 새로운 엔드포인트
• 스키마 변경 사항
• 비권장 필드

결론

OpenAPI는 크게 발전했습니다:

OpenAPI 3.0: 서버, 요청 본문, 콜백을 포함한 기초

OpenAPI 3.1: JSON 스키마 호환성, 웹훅 객체, 더 나은 다형성

OpenAPI 3.2: QUERY 메서드, 향상된 예제, 개선된 보안

Modern PetstoreAPI는 프로덕션에 즉시 사용 가능한 예시로 모든 기능을 시연하기 위해 OpenAPI 3.2를 사용합니다. 이는 현대 API 설계를 위한 참조 구현입니다.

어떤 OpenAPI 버전이든 작업하고, 사양의 유효성을 검사하고, 구현을 테스트하려면 Apidog를 사용하십시오.

자주 묻는 질문

OpenAPI 3.1 또는 3.2로 업그레이드해야 할까요?

사용하는 도구가 지원한다면 그렇습니다. OpenAPI 3.1의 JSON 스키마 호환성은 가치가 있습니다. OpenAPI 3.2는 QUERY 메서드와 같은 현대적인 패턴을 추가합니다.

제 OpenAPI 3.0 사양이 3.1 도구와 함께 작동할까요?

대부분은 작동하지만 nullable 및 exclusiveMinimum/exclusiveMaximum은 업데이트가 필요합니다.

코드 생성기가 OpenAPI 3.2를 지원하나요?

지원 범위가 넓어지고 있습니다. 코드 생성기의 문서를 확인하세요. 많은 생성기가 3.1을 지원하지만, 3.2를 지원하는 곳은 더 적습니다.

3.1에서 OpenAPI 3.2 기능을 사용할 수 있나요?

아니요. 기능에 맞는 버전을 사용하십시오. QUERY 메서드가 필요하면 3.2를 사용하십시오.

OpenAPI 사양의 유효성을 어떻게 검사하나요?

Apidog를 사용하여 사양을 가져오고 유효성을 검사하십시오. 스키마 유효성과 참조 무결성을 확인합니다.

완전한 OpenAPI 3.2 예시는 어디서 볼 수 있나요?

Modern PetstoreAPI는 완전한 프로덕션에 즉시 사용 가능한 OpenAPI 3.2 사양을 제공합니다.

웹훅과 콜백의 차이점은 무엇인가요?

웹훅은 서버에서 클라이언트로의 HTTP 요청입니다. 콜백은 OpenAPI 3.0에서 작업의 일부로 정의됩니다. OpenAPI 3.1+에는 전용 webhooks 객체가 있습니다.

OpenAPI 사양에 JSON 또는 YAML을 사용해야 하나요?

둘 다 작동합니다. YAML은 사람이 읽기 더 쉽습니다. JSON은 도구에서 처리하기 더 쉽습니다. Modern PetstoreAPI는 두 형식 모두를 제공합니다.