# OpenAPI

OpenAPI コネクターは、OpenAPI 仕様を使用して API エンドポイントを記述するあらゆるアプリケーションとの連携に使用できる、ユニバーサルコネクターです。

注 : 最適なエクスペリエンスを得るには、このコネクターを RESTful API (opens new window) とともに使用することをお勧めします。詳細については、「制限事項」セクションを参照してください。

# 基本情報

OpenAPI とは
Swagger ファイルとは
OpenAPI コネクターで行えること
OpenAPI コネクターを使用すべき場合
OpenAPI コネクターを使用してカスタムコネクターを作成する方法

# OpenAPI とは

OpenAPI は、RESTful Web サービスの記述、作成、使用、および視覚化のための、コンピューターで読み取り可能なインターフェイスとして機能する仕様です。

OpenAPI ドキュメントは、Swagger ファイルとも呼ばれ、以下のようなさまざまな目的で使用できます。

API ドキュメントの生成
多様なプログラミング言語でのサーバーとクライアントの生成
テストケースの生成の自動化
その他

詳細については、OpenAPI のリソース (opens new window)を参照してください。

# Swagger ファイルとは

Swagger ファイルは、API において使用できるエンドポイントを記述します。このファイルには以下のデータが含まれます。

エンドポイントメソッド
エンドポイントパス
ヘッダー
パラメータとクエリー文字列
リクエストとレスポンスのスキーマ

たとえば、こちらのサンプル Swagger ファイル (opens new window)の以下の箇所では、POST /pet エンドポイントを記述しています。

paths:
  /pet:
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      operationId: addPet
      requestBody:
        $ref: https://api.swaggerhub.com/domains/Colon-Org/PetStore-Objects/1.0#/components/requestBodies/PetRequest
      responses:
        '405':
          description: Invalid input
      security:
        - petstore_auth:
            - 'write:pets'
            - 'read:pets'

# OpenAPI コネクターで行えること

OpenAPI コネクターはユーザー指定の Swagger ファイルを解析し、そのファイルの内容に従って、Workato 内でアクション、入出力項目、オブジェクトといったユーザーインターフェイスを生成します。ただし、コネクターの品質は Swagger ファイルの内容に依存します。

インターフェイスをカスタマイズする必要がある場合は、OpenAPI コネクターをテンプレートとして使用して、カスタムコネクターを作成できます。たとえば、自分のコネクターにカスタムアイコンや認証が必要な場合は、OpenAPI コネクターをスタートポイントとして使用し、それを必要に応じてカスタマイズできます。

# OpenAPI コネクターを使用すべき場合

OpenAPI コネクターの使用は、以下の条件すべてに該当する場合に検討してください。

アプリケーション固有のコネクターとして利用できるものがない。

アプリケーションにより Swagger ファイルが提供されている。

Swagger ファイルに記述されている API が REST 規格 (opens new window)に従っている。

以下の図を利用すると、どのようなときに OpenAPI コネクターの使用を検討すべきであり、どのときに他のコネクターを使用したり、カスタムコネクターを作成したりすべきかを知ることができます。

Workato UI 内でハイライトされているオブジェクトピッカーフィールド

# OpenAPI コネクターを使用してカスタムコネクターを作成する方法

OpenAPI コネクターを使用するとアプリケーションにすばやく簡単に接続することができますが、その一方で、特定のアプリケーションに対するカスタムコネクターを作成したほうがよい場合もあります。

たとえば、以下のようなケースです。

アプリケーションの名前とアイコンを使用して UX を改善したい
コネクションの設定を簡素化したい
カスタム認証フローを実装したい

詳細については、「OpenAPI コネクターを使用したカスタムコネクターの作成」ガイドを参照してください。

注 : コネクターのコードをカスタマイズすると、新しいバージョンへのアップグレードが複雑になることがあります。詳細については、「OpenAPI コネクターのソースコードのアップグレード」ガイドを参照してください。

# Swagger のバージョンと形式

OpenAPI コネクターでは、以下の Swagger のバージョンと形式がサポートされています。

指定する Swagger ファイルは有効な YAML または JSON であり、サポートされているいずれかのバージョンの仕様に準拠している必要があります。

# 認証方法

OpenAPI コネクターでは、以下の認証方法がサポートされています。

認証なし
基本認証
ヘッダー認証
クエリーパラメータ認証
OAuth 2.0: 認証コード付与
OAuth 2.0: クライアント資格情報付与
OAuth 2.0: リソース所有者パスワード付与

詳細については、「OpenAPI コネクターの認証」ガイドを参照してください。

# インターフェイスのカスタマイズ

OpenAPI コネクターは、指定された Swagger ファイルの内容に基づいて、ユーザーインターフェイスを自動的に生成します。ユーザーエクスペリエンスを向上させるために、以下の要素をカスタマイズできます。

オブジェクト名とヒント
フィールド名とヒント
外部ドキュメントへのリンク
API 操作の分類
無視するフィールド

詳細と例については、「OpenAPI ユーザーインターフェイスのカスタマイズ」ガイドを参照してください。

# アクション

OpenAPI コネクターでは、以下のアクションがサポートされています。

Create record
Update record
Search records
Get record details by ID
Execute operation
Delete record
カスタムアクション

指定された Swagger ファイルを OpenAPI コネクターが解析する際、API 操作は上記のサポートされているアクションのいずれかに割り当てられます。たとえば、pet レコードを新規作成するエンドポイントは、 Create record (レコードの作成) アクションに割り当てられます。

詳細と例については、「OpenAPI ユーザーインターフェイスのカスタマイズ」ガイドを参照してください。

# 制限事項

OpenAPI コネクターを使用する場合は、以下のことに注意してください。

コネクターの品質は Swagger ファイルの内容に依存します。 レシピエディターのユーザーインターフェイスは、Swagger ファイルの内容から作成されます。たとえば、Swagger ファイルに API 操作やリクエスト/レスポンスフィールドが記述されていない場合、エンドユーザーのエクスペリエンスは理想的にはなりません。
このコネクターは、RESTful API で使用するように構築されています。 最適なエクスペリエンスを得るには、このコネクターを RESTful API (opens new window) で使用することをお勧めします。REST 以外の API を使用することもできますが、API 操作をアクションに分類する際に問題が発生する場合があります。

# 設定

OpenAPI コネクターを使用し始める準備は整っていますか。以下のガイドを参照してください。

Last updated: 2023/8/31 1:07:14