OpenAPI Specification 3.0のサポート - Cloud

Talend Cloud API Designerユーザーガイド

EnrichVersion
Cloud
EnrichProdName
Talend Cloud
EnrichPlatform
Talend API Designer
task
ジョブデザインと開発 > Designing APIs
Talend Cloud API Designerを使い、OpenAPI Specification (OAS) 3.0でAPIをデザインします。

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

OpenAPIの詳細は、Swaggerのドキュメントを参照してください。

コンポーネント

コンポーネントを使えば、API全体でさまざまなエレメントを再利用できます。エレメントとして使用できる項目は次のとおりです:
  • パス変数
  • クエリーパラメーター
  • ヘッダー
  • レスポンス

組み合わせ

複数のデータ型を組み合わせることによって新しいデータ型を作成できます。Talend Cloud API Designerでサポートされている組み合わせは次の2種類です:
  • コンポジション(allOf)を使えば、さまざまなスキーマのスキーマプロパティを集計できます。たとえば、nervousSystemskeletondigestiveSystemという既存のデータ型のプロパティをすべて再利用すれば、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では、一部のプロパティが読み取り専用や書き込み専用であると示すことができます。

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