3.6. OpenAPI 定義のインポート
新しいサービスを作成する場合、または既存のサービスを更新する場合は、ローカルファイルまたは URL から OpenAPI 定義をインポートすることができます。インポートのデフォルトのサービス名は、OpenAPI 定義の info.title で指定されます。ただし、--target_system_name=<NEW NAME> を使用して、このサービス名を上書きできます。この場合、そのサービス名がすでに存在する場合は更新され、存在しない場合は新しいサービス名が作成されます。
import openapi コマンドのフォーマットは以下のとおりです。
3scale import openapi [opts] -d=<destination> <specification>
OpenAPI <specification> は、以下のいずれかです。
-
/path/to/your/definition/file.[json|yaml|yml] -
http[s]://domain/resource/path.[json|yaml|yml]
例
$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.8 3scale import openapi [opts] -d=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} my-test-api.json
コマンドオプション
import openapi コマンドのオプションは以下のとおりです。
-d --destination=<value>-
3scale のターゲットインスタンス (
http[s]://<authentication>@3scale_domain形式) -t --target_system_name=<value>- 3scale のターゲットシステム名
--backend-api-secret-token=<value>- API ゲートウェイによってバックエンド API に送信されるカスタムシークレットトークン
--backend-api-host-header=<value>- API ゲートウェイによってバックエンド API に送信されるカスタムホストヘッダー
その他のオプションについては、3scale import openapi --help コマンドを参照してください。
OpenAPI のインポートルール
OpenAPI 定義をインポートする場合、以下のルールが適用されます。
- 定義は OpenAPI 2.0 または OpenAPI 3.0 として検証される。
- 3scale サービスのマッピングルールは、すべて削除される。
-
置き換えるためには、パターンの完全一致の使用により、すべてのメソッドの名前が OpenAPI 定義 (
operation.operationId) で定義されるメソッドと同一でなければならない。 - OpenAPI 定義に含まれるメソッドのみが変更される。
-
OpenAPI 定義にしか存在していなかったすべてのメソッドが、
Hitsメトリクスにアタッチされる。 - OpenAPI 定義のすべてのマッピングルールがインポートされる。これらについては API > Integration で確認できます。
-
サポートされるセキュリティースキームは、
apiKeyおよびoauth2(任意の OAuth フロータイプに対応) です。 OpenAPI 仕様は、以下の値のいずれかでなければなりません。
- 利用可能なパスのファイル名
-
toolbox がコンテンツをダウンロードすることのできる URL。サポートされるスキームは
httpおよびhttpsです。 -
stdin標準入力ストリームから読み込む。これは、値に-を設定することで制御されます。
仕様にセキュリティー要件がない場合、サービスは Open API とみなされます。ポリシーチェーンに default_credentials ポリシー (anonymous_policy とも呼ばれる) がまだない場合、toolbox はこのポリシーを追加します。default_credentials ポリシーは、オプションのパラメーター --default-credentials-userkey で提供される ユーザーキー で設定されます。
OpenAPI 3.0 の制約
OpenAPI 3.0 定義をインポートする場合、以下の制約が適用されます。
-
serversリストの最初のserver.url要素だけがプライベート URL として処理される。server.url要素のpathコンポーネントが、OpenAPI のbasePathプロパティーとして使用されます。 - toolbox は、パス項目および操作オブジェクトのサーバーを処理しない。
- セキュリティースキームオブジェクトでは、複数のフローはサポートされない。
