MENU

OpenAPI 3.0.0と3.1.0の違い

OpenAPI 3.0.0と3.1.0の違いは、主に以下の点にあります。これらの違いは、API仕様の柔軟性と表現力を向上させ、より多くのユースケースをカバーできるようにすることを目的としています。

主な違い

  1. JSON Schemaとの互換性:
  • 3.0.0: OpenAPI 3.0.0では、JSON Schemaのバージョン2019-09をベースにしていますが、完全な互換性はありませんでした。一部の構文や機能はサポートされていませんでした。
  • 3.1.0: OpenAPI 3.1.0は、JSON Schema 2020-12を完全にサポートしています。これにより、より複雑なデータバリデーションやスキーマの定義が可能となります。
  1. エクステンションの削除:
  • 3.0.0: 特定の拡張（エクステンション）が存在し、これが標準的なJSON Schemaの構文と衝突することがありました。
  • 3.1.0: JSON Schemaとの互換性を向上させるために、これらの拡張が削除されました。
  1. Webhooksのサポート:
  • 3.0.0: Webhookの概念は仕様に明確には含まれていませんでした。
  • 3.1.0: Webhooksが正式にサポートされ、webhooksセクションで定義できるようになりました。これにより、APIのイベント駆動型の設計が容易になります。
  1. Componentsの変更:
  • 3.0.0: componentsセクションには、schemas、responses、parameters、examples、requestBodies、headers、securitySchemes、links、callbacksが含まれていました。
  • 3.1.0: componentsセクションが拡張され、新たにサポートされる要素が追加されました。
  1. OAuth 2.0 Security Schemeの改良:
  • 3.0.0: OAuth 2.0のセキュリティスキームの定義はやや限定的でした。
  • 3.1.0: OAuth 2.0のセキュリティスキームの定義が改良され、OpenID Connect DiscoveryとOAuth 2.0のサポートが強化されました。
  1. Pathsのパターンマッチング:
  • 3.0.0: pathsセクションのパスは静的な文字列で定義されていました。
  • 3.1.0: パスのパターンマッチングが導入され、より柔軟なルーティングが可能になりました。
  1. 互換性とバリデーションの改善:
  • 3.0.0: 一部のバリデーションや互換性の問題が存在しました。
  • 3.1.0: JSON Schema 2020-12の完全サポートにより、バリデーション機能が大幅に改善されました。

具体例

以下は、OpenAPI 3.0.0と3.1.0の簡単なサンプルの違いを示します。

OpenAPI 3.0.0の例

openapi: 3.0.0
info:
  title: Sample API
  description: API for demonstrating OpenAPI 3.0.0
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          description: A list of pets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

OpenAPI 3.1.0の例

openapi: 3.1.0
info:
  title: Sample API
  description: API for demonstrating OpenAPI 3.1.0
  version: 1.0.0
paths:
  /pets:
    get:
      summary: List all pets
      responses:
        '200':
          description: A list of pets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
webhooks:
  newPet:
    post:
      summary: New pet added
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string

OpenAPI 3.1.0のリリースにより、APIの記述と管理がより柔軟かつ強力になりました。これにより、開発者はより高度なAPI設計と実装を行うことができます。

コラム