OpenAPI 3.2 vs 3.1 vs 3.0 の変更点：違いを徹底比較

要約

OpenAPI 3.1では、JSONスキーマとの完全な互換性、Webhook、およびディスグリミネーターの改善が追加されました。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は1つのホストのみをサポートしていました。

2. リクエストボディオブジェクト

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

Swagger 2.0のbodyパラメーターよりも明確になりました。

3. 再利用可能なコンポーネント

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

Swagger 2.0のdefinitionsよりも優れた整理が可能です。

4. コールバック

非同期コールバック（Webhook）を定義します。

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

5. リンク

操作間の関係を定義します。

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

制限事項

1. JSONスキーマの非互換性

OpenAPI 3.0はJSONスキーマドラフト5のサブセットを使用しており、完全なJSONスキーマではありませんでした。これが検証の問題を引き起こしました。

2. Webhookオブジェクトなし

Webhookはコールバックとして定義されており、混乱を招きました。

3. 限られたディスグリミネーター

ポリモーフィズムのサポートは基本的なものでした。

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"]  # Standard JSON Schema

利点：

• 任意のJSONスキーマバリデーターを使用できる
• OpenAPIと他のツール間でスキーマを共有できる
• 完全なJSONスキーマ機能にアクセスできる

2. Webhookオブジェクト

以前（OpenAPI 3.0）：

# Webhooks defined as callbacks (confusing)
paths:
  /subscribe:
    post:
      callbacks:
        orderUpdate:
          # webhook definition

以降（OpenAPI 3.1）：

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

APIエンドポイントとWebhook間のより明確な分離。

3. ディスグリミネーターの改善

より良いポリモーフィズムのサポート：

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 identifier

5. PathItem $ref

パスアイテム全体を参照します。

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

破壊的変更

1. nullableの削除

代わりにtype: [string, "null"]を使用します。

2. exclusiveMinimum/exclusiveMaximumの変更

数値ではなく、ブール値になりました。

3. example と examples

より厳格な検証。

OpenAPI 3.2の最新機能

OpenAPI 3.2（リリース日未定、ドラフト利用可能）では、最新のAPIパターンが追加されています。

1. QUERYメソッドのサポート

複雑な検索のためのHTTP QUERYメソッド：

paths:
  /pets/search:
    query:  # New method
      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:
  propertyName: type
  mapping:
    cat: Cat
    dog: Dog
    bird: '#/components/schemas/Bird'  # Can mix local and $ref

5. 非推奨サポートの改善

特定のフィールドを非推奨にする：

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. Webhook

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の置き換え：

# Before
type: string
nullable: true

# After
type: [string, "null"]

2. exclusiveMinimum/exclusiveMaximumの更新：

# Before
minimum: 0
exclusiveMinimum: true

# After
minimum: 0
exclusiveMinimum: 0

3. Webhookの移動：

# Before
paths:
  /subscribe:
    callbacks:
      # webhook

# After
webhooks:
  # webhook

3.1から3.2へ

1. 適切な場所にQUERYメソッドを追加する：

/pets/search:
  query:  # New in 3.2
    # complex search

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スキーマの互換性、Webhookオブジェクト、より良いポリモーフィズム

OpenAPI 3.2: QUERYメソッド、強化された例、改善されたセキュリティ

Modern PetstoreAPIは、OpenAPI 3.2を使用して、すべての機能を本番環境で利用可能な例とともに示しています。これは、最新のAPI設計のリファレンス実装です。

Apidogを使用して、任意のOpenAPIバージョンで作業し、仕様を検証し、実装をテストできます。

よくある質問

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をサポートしているものは少ないです。

OpenAPI 3.2の機能を3.1で使用できますか？

いいえ、できません。機能に合ったバージョンを使用してください。QUERYメソッドが必要な場合は3.2を使用してください。

OpenAPI仕様をどのように検証しますか？

Apidogを使用して、仕様をインポートして検証します。スキーマの有効性と参照の整合性をチェックします。

完全なOpenAPI 3.2の例はどこで見ることができますか？

Modern PetstoreAPIは、完全で本番環境で利用可能なOpenAPI 3.2仕様を提供しています。

Webhookとコールバックの違いは何ですか？

WebhookはサーバーからクライアントへのHTTPリクエストです。コールバックはOpenAPI 3.0で操作の一部として定義されていました。OpenAPI 3.1以降には専用のwebhooksオブジェクトがあります。

OpenAPI仕様にはJSONとYAMLのどちらを使用すべきですか？

どちらも機能します。YAMLは人間にとって読みやすく、JSONはツールにとって処理しやすいです。Modern PetstoreAPIは両方の形式を提供しています。