Workato：OpenAPI 2.xで提供されているファイルをOpenAPI 3.x形式へ変換してカスタムコネクタ化する

はじめに

Workatoには、OpeAPI形式に準拠したJSONまたはYAMLファイルをもとにカスタムコネクタを作成する機能が用意されています。

この機能を利用すると、コードを書くことなくWorkatoのカスタムコネクタを自動で作成することが出来ます。すぐに使える、あるいは少々の調整を加えることで使い始められるため、何より全てのコードを１から書く必要が無いため、標準コネクタあるいはコミュニティライブラリ上でコネクタが提供されていない場面において非常に重宝します。

しかし、この機能の前提として、OpenAPI 3.0(3.x)形式に準拠したJSONまたはYAMLファイルである必要があります。

一方、世の中にはまだまだ多くのOpenAPI 2.xで提供されているケースが多く存在します。 一例として、 「マネーフォワード クラウド経費API」のAPIドキュメント(Swagger) では、OpenAPI 2.xに準拠したJSONファイルを提供しています。

このJSONファイルをWorkatoへインポートしようとすると、次の通りエラーになります。

これを解決する方法は、OpenAPI 2.x から 3.xへの変換を行うか、APIドキュメントをもとにスクラッチでカスタムコネクタを実装するか、の2択になります。今回は、OpenAPI 2.x から 3.xへ変換を行い、変換後のファイルからカスタムコネクタを作成する方法を紹介します。

対応方法

【１】OpenAPI 2.0 -> 3.0 へ変換する

1. 変換したいOpenAPI 2.0形式のファイルの内容（テキスト）をコピーする

2. Swagger Editorを開く

以下のURLへアクセスします。

3. Swagger Editor上へコピーした内容を貼り付ける

※JSONを貼付すると、自動的にYAMLに変換されます。

Swagger Editor上へコピーした内容を貼り付けると、次のような表示（コピー元のAPIドキュメントと概ね同様の表示）になります。

なお、貼り付けた内容にエラーが含まれる場合、次の通りエラーメッセージが表示されます。内容を確認し、必要に応じて修正を行います。なお、カスタムコネクタ作成に影響しない（インポートに影響しない）エラーである場合は、ここでは一旦無視して、インポート後にカスタムコネクタ側を修正するのが良いでしょう。

4. OpenAPI 3.0形式に変換する

「Edit」－「Convert to OpenAPI 3」をクリックします。

「Convert」をクリックします。

変換が完了すると、バージョンが 3.x （ここでは 3.0.1）と表示され、OpenAPI 3.xに準拠した内容に変換されたことが確認できます。

5. JSON形式で出力（ダウンロード）する

Workatoのカスタムコネクタ作成機能において、YAML形式でのインポートは失敗する場合があるため、JSON形式で出力します。

「File」－「Convert and save as JSON」をクリックすると、JSON形式で出力することができます。

【２】Workatoへインポートする

1. Connector SDKを開き、「New Connector」をクリックします。

2. 「Import OpenAPI Specification」をクリックします。

3. 【１】で出力したJSONファイルを指定し、「Next」をクリックします。

ダイアログからファイルを選択するか、ドラッグ＆ドロップでJSONファイルを指定します。
その後、「Next」をクリックします。

4. インポート結果を確認します。

正常にインポートされると、次の画面が表示されます。
内容を確認し、インポートするアクションを選択のうえ「Go to editor」をクリックします。

※ここで表示される結果はグループ単位でまとめられている（実際のメソッドに対して少ない数で表示される）場合があります。カスタムコネクタのアクションは、グループ展開後の結果で出力されます（実際のメソッドと同数で出力されます）ので、問題ありません。

※インポートするアクションが１つも選択されていないと、次の画面でエラーになります。

5. カスタムコネクタの編集画面が表示されます。

適宜テストを実施し、問題なく利用できることを確認します。

「Release this connector」をクリックすると、カスタムコネクタをレシピで利用できるようになります。

注意事項

• コネクタの生成結果は、インポートされるOpenAPI形式のファイルの品質に依存します。このため、OpenAPI形式のファイルの品質によっては、期待する動作とならない（エラーになる等）場合があります。その際は、インポート結果の調整で対応ください。
• OpenAPI形式のファイルをインポートしてカスタムコネクタを生成する機能は、2023/12/18現在においてはベータ版で提供されています。このため、OpenAPI3.0に準拠しているものであっても、正常にインポートできない、あるいはインポートに失敗する場合があります。（例：Workatoで扱えない文字が含まれている等）