OpenAPI 仕様から API プロキシを作成する | Apigee ドキュメント

このチュートリアルでは、Apigee Edge 管理 UI を使って OpenAPI 仕様から Edge API プロキシを作成する方法について学習します。cURL などの HTTP クライアントで API プロキシを呼び出す際、API プロキシはリクエストを Apigee 疑似ターゲットサービスに送信します。

Open API Initiative について

「Open API Initiative（OAI）は、Swagger 仕様に基づく、ベンダーに依存しない API 記述形式の作成、進化、促進に注力しています。」Open API Initiative について詳しくは、https://openapis.org をご覧ください。

OpenAPI 仕様では、標準的な形式を使用して RESTful API を記述します。JSON または YAML 形式で記述された OpenAPI 仕様は、マシン可読でありながら、人間も簡単に読んで理解できます。この仕様は、ベースパス、パスと動詞、ヘッダー、クエリパラメータ、オペレーション、コンテンツタイプ、レスポンス記述などの API の要素を記述しています。また、OpenAPI 仕様は API ドキュメントの生成にもよく使用されます。

Apigee 疑似ターゲットサービスについて

このチュートリアルで使用される Apigee 疑似ターゲットサービスは、Apigee でホストされ、単純なデータを返します。API キーやアクセストークンは必要ありません。実際に、ウェブブラウザでアクセスできます。次をクリックして、試してみましょう。

http://mocktarget.apigee.net

ターゲットサービスからあいさつ Hello, guest! が返ってきます。

疑似ターゲットサービスがサポートする完全な API の一覧については、次の URL をクリックしてください。

http://mocktarget.apigee.net/help

必要なもの

Apigee Edge アカウント。Apigee Edge のアカウントがない場合は、Apigee Edge アカウントの作成に沿って登録できます。
OpenAPI 仕様。このチュートリアルでは、Apigee の疑似ターゲットサービス http://mocktarget.apigee.net を記述した mocktarget.yaml OpenAPI 仕様を使用します。詳しくは、https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi をご覧ください。
cURL。コマンドラインまたはウェブブラウザから API 呼び出しを行うために、マシンにインストールされている必要があります。

API プロキシの作成

Edge

Edge UI を使用して OpenAPI 仕様から API プロキシを作成するには:

https://apigee.com/edge にログインします。
メインウィンドウで [API Proxies] をクリックします。
左側のナビゲーションバーで [Develop] > [API Proxies] を選択することもできます。
[+ Proxy] をクリックします。
[Create Proxy] ウィザードで、[Reverse proxy (most common)] テンプレートの [Use OpenAPI Spec] をクリックします。
[Import from URL] をクリックしてから、次の情報を入力します。
- OpenAPI Spec URL: [URL] フィールドに、OpenAPI 仕様の GitHub にある未加工コンテンツへのパスを入力します。
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- Spec name: OpenAPI 仕様の名前（Mock Target など）を入力します。
  この名前は、OpenAPI 仕様を仕様ストアに保存するために使用されます。仕様を管理するをご覧ください。

[Import] をクリックします。

[Create Proxy] ウィザードの [Details] ページが表示されます。以下に示すように、OpenAPI 仕様で定義されている値がフィールドに事前入力されます。

次の表に、OpenAPI 仕様のプロパティを使用して事前に入力されるデフォルト値を示します。表の後に、使用されるプロパティを示す OpenAPI 仕様の抜粋を示します。

フィールド	説明	デフォルト
Name	API プロキシの名前。例: `Mock-Target-API`。	OpenAPI 仕様の `title` プロパティ（スペースはダッシュに置き換えられる）
Base path	組織内で API プロキシを一意に識別するパスコンポーネント。API プロキシの一般公開される URL は、組織名、この API プロキシがデプロイされる環境、このベースパスで構成されます。例: `http://myorg-test.apigee.net/mock-target-api`	[Name] フィールドの内容（すべて小文字に変換される）
Description	API プロキシの説明。	OpenAPI 仕様の `description` プロパティ
Target (Existing API)	API プロキシに代わって呼び出されるターゲット URL。オープンなインターネット経由でアクセスできる任意の URL を使用できます。例: `http://mocktarget.apigee.net`	OpenAPI 仕様の `servers` プロパティ

次の OpenAPI 仕様からの抜粋に、フィールドへの事前入力に使用されるプロパティを示します。

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

[Description] フィールドを次のように編集します。API proxy for the Apigee mock target service endpoint.
[Next] をクリックします。
[Common policies] ページで、[Security: Authorization] の [Pass through (no authorization)] が選択されていることを確認してから、[Next] をクリックします。
[Flows] ページで、すべてのオペレーションが選択されていることを確認します。
ヒント: 条件付きフローは、OpenAPI 仕様の paths オブジェクト内で定義されているオペレーションから自動的に生成されます。条件付きフローでは「条件付きフローが定義されている場合、該当ロジックを実行する」ということを Edge に指示します。たとえば、API 呼び出しが /xml リソース（条件）に対する GET である場合、（条件付きフローに添付されたポリシーを介して）レスポンスを JSON に変換します。トランザクションごとに 1 つのフロー（最初に true と評価される条件を持つフロー）のみが実行されます。
[Next] をクリックします。
[Virtual hosts] ページで [default] と [secure] を選択してから、[Next] をクリックします。
[Summary] ページの [Optional Deployment] で [Test] 環境が選択されていることを確認してから、[Create and deploy] をクリックします。

Apigee によって新しい API プロキシが作成され、テスト環境にデプロイされます。
[Edit proxy] をクリックして、API プロキシの [Overview] ページを表示します。

Classic Edge（Private Cloud）

Classic Edge UI を使用して OpenAPI 仕様から API プロキシを作成するには:

https://apigee.com/edge にログインします。
メインウィンドウで [API Proxies] をクリックします。
左側のナビゲーションバーで [Develop] > [API Proxies] を選択することもできます。
[+ Proxy] をクリックします。
[Create Proxy] ウィザードで [Reverse proxy (most common)] を選択して、[Use OpenAPI] をクリックします。
[Import from a URL] をクリックして OpenAPI 仕様の名前を入力します。[URL] フィールドに、OpenAPI 仕様の GitHub にある未加工コンテンツのパスを入力します。

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
[Select] をクリックします。

[Next] をクリックします。

[Create Proxy] ウィザードの [Details] ページが表示されます。次の図に示すように、OpenAPI 仕様で定義された値がフィールドに事前入力されます。

次の表に、OpenAPI 仕様のプロパティを使用して事前に入力されるデフォルト値を示します。表の後に、使用されるプロパティを示す OpenAPI 仕様の抜粋を示します。

フィールド	説明	デフォルト
Proxy Name	API プロキシの名前。例: `Mock-Target-API`。	OpenAPI 仕様の `title` プロパティ（スペースはダッシュに置き換えられる）
Proxy Base Path	組織内で API プロキシを一意に識別するパスコンポーネント。API プロキシの一般公開される URL は、組織名、この API プロキシがデプロイされる環境、このベースパスで構成されます。例: `http://myorg-test.apigee.net/mock-target-api`	[Name] フィールドの内容（すべて小文字に変換される）
Existing API	API プロキシに代わって呼び出されるターゲット URL。オープンなインターネット経由でアクセスできる任意の URL を使用できます。例: `http://mocktarget.apigee.net`	OpenAPI 仕様の `servers` プロパティ
Description	API プロキシの説明。	OpenAPI 仕様の `description` プロパティ

次の OpenAPI 仕様からの抜粋に、フィールドへの事前入力に使用されるプロパティを示します。

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

[Description] フィールドを次のように編集します。API proxy for the Apigee mock target service endpoint.
[Next] をクリックします。
[Flows] ページで、すべてのオペレーションが選択されていることを確認します。
ヒント: 条件付きフローは、OpenAPI 仕様の paths オブジェクト内で定義されているオペレーションから自動的に生成されます。条件付きフローでは「条件付きフローが定義されている場合、該当ロジックを実行する」ということを Edge に指示します。たとえば、API 呼び出しが /xml リソース（条件）に対する GET である場合、（条件付きフローに添付されたポリシーを介して）レスポンスを JSON に変換します。トランザクションごとに 1 つのフロー（最初に true と評価される条件を持つフロー）のみが実行されます。
[Next] をクリックします。
[Security] ページで、セキュリティオプションとして [Pass through (none)] を選択してから、[Next] をクリックします。
[Virtual Hosts] ページで、すべての仮想ホストが選択されていることを確認してから、[Next] をクリックします。
[Build] ページで test 環境が選択されていることを確認してから、[Build and Deploy] をクリックします。
[Summary] ページに、新しい API プロキシが正常に作成され、test 環境にデプロイされたことを示す確認応答が表示されます。
[Mock-Target-API] をクリックして、API プロキシの [Overview] ページを表示します。

これで完了ですOpenAPI 仕様から API プロキシを作成できました。次は、その動作をテストします。

API プロキシのテスト

ここでは、cURL またはウェブブラウザを使用して、Mock-Target-API API のテストを行います。

ターミナルウィンドウで、次の cURL コマンドを実行します。URL 内の組織名はご自分の組織名に置き換えてください。

curl http://<org_name>-test.apigee.net/mock-target-api

レスポンス

次のようなレスポンスが表示されます。

Hello, Guest!

成功です。簡単な API プロキシを OpenAPI 仕様から構築し、テストできました。

XML to JSON ポリシーを追加する

次に、OpenAPI 仕様から API プロキシを作成したときに自動的に生成された View XML Response 条件付きフローに XML to JSON ポリシーを追加します。このポリシーは、ターゲットの XML レスポンスを JSON レスポンスに変換します。

最初に、ポリシーの追加後に受け取る結果と元の結果を比較できるように、API を呼び出します。ターミナルウィンドウで、次の cURL コマンドを実行します。ターゲットサービスの /xml リソースを呼び出します。これにより、ネイティブに XML の単純なブロックが返されます。URL 内の組織名はご自分の組織名に置き換えてください。

curl http://<org_name>-test.apigee.net/mock-target-api/xml

レスポンス

次のようなレスポンスが表示されます。

<root>
  <city>San Jose</city>
  <firstName>John</firstName>
  <lastName>Doe</lastName>
  <state>CA</state>
</root>

次に、XML レスポンスを JSON に変換してみましょう。XML to JSON ポリシーを API プロキシの [View XML Response] 条件付きフローに追加します。

Edge UI で、[Mock-Target-API] の [Overview] ページの右上にある [Develop] タブをクリックします。
左側の [Navigator] ナビゲーションパネルの [Proxy Endpoints] > [default] で、[View XML Response] 条件付きフローをクリックします。
画面下部で、フローの [Response] に対応する [+ Step] ボタンをクリックします。

[Add Step] ダイアログが開き、追加できるすべてのポリシーの分類リストが表示されます。
[Mediation] カテゴリまでスクロールし、[XML to JSON] を選択します。
[Display Name] と [Name] はデフォルト値のままにします。
[Add] をクリックします。XML to JSON ポリシーがレスポンスに適用されます。
[Save] をクリックします。

ポリシーを追加したら、cURL を使用して API をもう一度呼び出します。同じ /xml リソースを呼び出していることに注意してください。ターゲットサービスは依然として XML のブロックを返しますが、API プロキシのポリシーはレスポンスを JSON に変換します。次の呼び出しを行います。

curl http://<org_name>-test.apigee.net/mock-target-api/xml

XML レスポンスが JSON に変換されていることに注目してください。

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

これで完了です条件付きフローに追加したポリシーの実行を正常にテストできました。