OpenAPI Specification 3.0のサポート

最終更新日時: 2026/10/20

API Contracts を使い、OpenAPI Specification (OAS) 3.0 で API をデザインします。

OpenAPI Specification 3.0に追加された新機能によって、APIデザインの表現性と生産性がさらに向上しました。

OpenAPIの詳細は、Swaggerのドキュメントをご覧ください。

コンポーネント

コンポーネントを使えば、API全体でさまざまなエレメントを再利用できます。エレメントとして使用できる項目は次のとおりです:

パス変数
クエリーパラメーター
ヘッダー
レスポンス

コンビネーション

複数のデータ型を組み合わせることによって新しいデータ型を作成できます。API Contracts は、2 種類の組み合わせをサポートしています。

コンポジション(allOf)を使えば、さまざまなスキーマのスキーマプロパティを集計できます。たとえば、既存の型 Contact および Error のすべてのプロパティを再利用して、データ型 Company を定義できます。
ポリモーフィズム(oneOf/anyOf)を使えば、さまざまなデータ型のプロパティを使用するエンティティを作成できます。
- oneOfを使えば、選択されたいずれかの種類のプロパティが含まれるデータ型を定義できます。たとえば、サービスアカウントに関する情報を取得するオペレーションを作成する場合、oneOf の組み合わせを使用してレスポンスを定義し、Error のすべてのプロパティ、または ServiceAccountCount のすべてのプロパティのいずれかを取得できます。
- anyOfを使えば、選択された種類の1つまたは複数のプロパティが含まれるデータ型を定義できます。例えば、異なるプロパティを含むデータ型 nervousSystem と型 skeleton を定義し、anyOf の組み合わせを使用して、これらの型のいずれかのプロパティを含むデータ型を作成できます。
  anyOfというコンビネーションは、選択された少なくとも1つのデータ型の必須パラメーターをすべて含んでいる限り有効です。以下の例では、nervousSystem 型の brain_weight プロパティと、skeleton の skull_height および teeth プロパティを使用しています。

コンポジションとポリモーフィズムに関する詳細は、Inheritance and Polymorphism and Difference Between anyOf and oneOfをご覧ください。

レスポンス

OAS 3.0では、操作用に新しいタイプのレスポンスを定義できます:

レスポンス範囲: 200 などのレスポンスを定義する代わりに、2XX と設定して 200 から 299 までのレスポンスを含めることができます。
デフォルトのレスポンス: 特定のレスポンスやレスポンス範囲が定義されていない場合は、デフォルトで返されるレスポンスを設定することもできます。

明示的コードで定義されたレスポンスはレスポンス範囲やデフォルトのレスポンスに優先し、レスポンス範囲はデフォルトのレスポンスに優先します。次の例では以下のことが行われます。

204 レスポンスが定義されており、他のレスポンスよりも優先されます。
2XX レスポンスは、レスポンスコード 200～203 および 205～299 に適用されます。
default レスポンスは、すべての 1XX、3XX、4XX、5XX レスポンスに適用されます。

セキュリティ

OAS 3.0では、API用に次のセキュリティスキームが新たに採用されています:

ベアラー認証
OpenIdConnect

制限

OAS 3.0では、一部のプロパティが読み取り専用や書き込み専用であると示すことができます。

このオプションはデータ型でのみ利用可能で、操作レベルでのリクエストやレスポンスには定義できません。

このページは役に立ちましたか?

このページまたはコンテンツにタイポ、ステップの省略、技術的エラーなどの問題が見つかった場合はお知らせください。

こちらにフィードバックをお寄せください