Talend Cloud API Designerを使い、OpenAPI Specification (OAS) 3.0でAPIをデザインします。
OpenAPI Specification 3.0に追加された新機能によって、APIデザインの表現性と生産性がさらに向上しました。
OpenAPIの詳細は、Swaggerのドキュメントをご覧ください。
コンポーネント
コンポーネントを使えば、API全体でさまざまなエレメントを再利用できます。エレメントとして使用できる項目は次のとおりです:
- パス変数
- クエリーパラメーター
- ヘッダー
- レスポンス
コンビネーション
複数のデータ型を組み合わせることによって新しいデータ型を作成できます。Talend Cloud API Designerでサポートされているコンビネーションは次の2種類です:
- コンポジション(allOf)を使えば、さまざまなスキーマのスキーマプロパティを集計できます。たとえば、nervousSystem、skeleton、digestiveSystemという既存のデータ型のプロパティをすべて再利用すれば、anatomyというデータ型を定義できます。
- ポリモーフィズム(
oneOf/anyOf)を使えば、さまざまなデータ型のプロパティを使用するエンティティを作成できます。-
oneOfを使えば、選択されたいずれかの種類のプロパティが含まれるデータ型を定義できます。たとえば、臓器に関する情報を取得するための操作を作成する場合、oneOfというコンビネーションを使ってレスポンスを定義すれば、脳の全プロパティか心臓の全プロパティのいずれかを取得できます。
-
anyOfを使えば、選択された種類の1つまたは複数のプロパティが含まれるデータ型を定義できます。たとえば、さまざまなプロパティが含まれるnervousSystemおよびskeletonという2つのデータ型を定義し、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というレスポンスが定義され、その他のレスポンスに優先します。
- 200～203および205～299というレスポンスコードには、2XXというレスポンスが適用されます。
- 1XX、3XX、4XX、5XXというレスポンスにはすべて、デフォルトのレスポンスが適用されます。
セキュリティ
OAS 3.0では、API用に次のセキュリティスキームが新たに採用されています:
- ベアラー認証
- OpenIdConnect
制限
OAS 3.0では、一部のプロパティが読み取り専用や書き込み専用であると示すことができます。
このオプションはデータ型でのみ利用可能で、操作レベルでのリクエストやレスポンスには定義できません。
