OpenAPI Specification 3.0のサポート

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

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

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

コンポーネント

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

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

コンビネーション

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

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

コンポジションとポリモーフィズムに関する詳細は、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では、一部のプロパティが読み取り専用や書き込み専用であると示すことができます。

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

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

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

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