# OpenAPI Specification 3.0のサポート

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

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

OpenAPIの詳細は、[Swaggerのドキュメント](https://swagger.io/docs/specification/about/)をご覧ください。

## コンポーネント

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

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

## コンビネーション

複数のデータ型を組み合わせることによって新しいデータ型を作成できます。Talend Cloud API Designerでサポートされているコンビネーションは次の2種類です:

* コンポジション(allOf)を使えば、さまざまなスキーマのスキーマプロパティを集計できます。たとえば、既存の型であるContactとErrorのすべてのプロパティを再利用することで、Companyというデータ型を定義できます。 ![コンポジションの例。](https://help.qlik.com/talend/ja-JP/api-designer-user-guide/Resources/images/all_of.png)
* ポリモーフィズム(oneOf /anyOf)を使えば、さまざまなデータ型のプロパティを使用するエンティティを作成できます。
  * oneOfを使えば、選択されたいずれかの種類のプロパティが含まれるデータ型を定義できます。たとえば、サービスアカウントに関する情報を取得する操作を作成する場合、oneOfの組み合わせを使用してレスポンスを定義することで、Errorのすべてのプロパティ、あるいはServiceAccountCountのすべてのプロパティのいずれかを取得できるように設定できます。 ![ポリモーフィズムの例。](https://help.qlik.com/talend/ja-JP/api-designer-user-guide/Resources/images/oneof.png)

  * anyOfを使えば、選択された種類の1つまたは複数のプロパティが含まれるデータ型を定義できます。たとえば、さまざまなプロパティが含まれるnervousSystemおよびskeletonという2つのデータ型を定義し、anyOfというコンビネーションを使えば、いずれかのデータ型のプロパティがすべて含まれるデータ型を作成できます。

    anyOfというコンビネーションは、選択された少なくとも1つのデータ型の必須パラメーターをすべて含んでいる限り有効です。次の例では、nervousSystemというデータ型のbrain\_weightプロパティと、skeletonというデータ型のskull\_heightおよびteethプロパティの両方が使用されています。

    ![nervousSystemデータ型とskeletonデータ型を使ったコンビネーションの例。](https://help.qlik.com/talend/ja-JP/api-designer-user-guide/Resources/images/anyof.png)

コンポジションとポリモーフィズムに関する詳細は、[Inheritance and Polymorphism](https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/) and [Difference Between anyOf and oneOf](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/#anyof-vs-oneof)をご覧ください。

## レスポンス

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

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

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

* 204というレスポンスが定義され、その他のレスポンスに優先します。
* 200～203および205～299というレスポンスコードには、2XXというレスポンスが適用されます。
* 1XX、3XX、4XX、5XXというレスポンスにはすべて、デフォルトのレスポンスが適用されます。

![\[Responses\] (レスポンス)セクション。](https://help.qlik.com/talend/ja-JP/api-designer-user-guide/Resources/images/responses-headers-api.png)

## セキュリティ

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

* ベアラ認証
* OpenIdConnect

## 制限

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

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

![制限の例。](https://help.qlik.com/talend/ja-JP/api-designer-user-guide/Resources/images/designer_restrictions.png)

### このセクション内

* [説明フィールドの使用](https://help.qlik.com/talend/ja-JP/api-designer-user-guide/Cloud/using-description-fields)