API Gateway:OASに基づくAPIのエクスポート

概要

このトピックでは、OAS標準に基づいてAPI GatewayからAPIをエクスポートする方法について説明します。 次の項目では、この機能とAPI GatewayのAPIインポート機能を組み合わせて使用することでできることを説明します。 APIインポート機能の詳細については、「OAS準拠のAPIのインポート」をご参照ください。

1. アカウント、リージョン、またはプラットフォーム間でAPIを移行する: OAS準拠のAPIをAPI Gatewayまたは別のプラットフォームから簡単にエクスポートし、これらのAPIを別のAlibaba Cloudアカウントまたはリージョン、または別のプラットフォームのインスタンスにインポートできます。

2. APIの公開と拡張: OAS準拠のAPI定義をAPI GatewayでAPIリソースに変換できます。 これにより、必要に応じてAPIの機能と動作をすばやく作成、設定、カスタマイズまたは拡張できます。 API Gatewayの柔軟性により、信頼性の高い安全な方法で、APIアクセス許可の管理、トラフィックの抑制、およびリクエストの転送が可能になります。

3. 統合と共同作業: エクスポートしたAPIを、OAS標準に基づく他の開発ツールやプラットフォームと簡単に統合できます。 これにより、API共有によりコミュニケーションと開発のワークロードが軽減されるため、チームや他の開発者とのコラボレーションを改善できます。

OAS準拠のAPIのエクスポート

APIグループ全体または特定のAPIをエクスポートできます。

手順

1. APIグループのエクスポート

   1. API Gatewayコンソールにログインします。

   2. 左側のナビゲーションウィンドウで、[APIの管理] > [APIグループ] を選択します。

   3. [APIグループ] ページで、エクスポートするAPIグループを見つけます。 をクリックし、[操作] 列で [API定義のエクスポート] を選択します。

   4. [API定義のエクスポート] ダイアログボックスで、[データ形式] 、[ステージ] 、および [拡張定義のエクスポート] パラメーターを指定します。 [確認] をクリックします。

2. 特定のAPIのエクスポート

   1. API Gatewayコンソールにログインします。

   2. 左側のナビゲーションウィンドウで、[APIの管理] > [API] を選択します。

   3. [API] ページで、エクスポートするAPIを選択し、リストの下にある [詳細]> [API定義のエクスポート] を選択します。

   4. [API定義のエクスポート] ダイアログボックスで、[データ形式] 、[ステージ] 、および [拡張定義のエクスポート] パラメーターを指定します。 [確認] をクリックします。

拡張API定義

[拡張定義のエクスポート] パラメーターで [はい] を選択した場合、API Gatewayに関連する拡張フィールドがエクスポートされたAPIファイルに追加されます。 次の表では、フィールドについて説明します。

説明

1. グループ単位でエクスポートすると、グループのベースパスがエクスポートされます。

2. 一度に最大300のAPIをエクスポートできます。 エクスポートするグループに300を超えるAPIが含まれている場合、最初の300 APIがエクスポートされます。

3. APIグループのモデル定義を解析できない場合、モデル定義はエクスポートされません。

4. 特定のAPIをエクスポートすると、選択したすべてのAPIが同じファイルにエクスポートされます。

5. APIのパスとメソッドが同じ場合、いずれかのAPIのみがエクスポートされます。

6. [拡張定義のエクスポート] パラメーターで [いいえ] を選択した場合、エクスポートされたファイルのOperationId値は、export1ByGETなどのAPI定義のリクエストパスとリクエストメソッドの連結文字列になります。

7. [拡張定義のエクスポート] パラメーターで [はい] を選択した場合、バインドされたプラグイン、承認されたアプリケーション、APIグループのバインドされたドメイン名、さまざまな環境のバックエンドサービス定義など、APIに関する追加情報はエクスポートされません。

例

次のサンプルコードでは, APIグループとその拡張API定義をエクスポートします。

swagger: '2.0'
info:
  description: Export from api group xxx
  version: 1.0.0
  title: Api Gateway API
basePath: /export
paths:
  /export1/{pathParam}:
    get:
      summary: test export job 1.
      operationId: export1pathParamByGET
      schemes:
        - http
        - https
      parameters:
        - name: pathParam
          in: path
          description: the path parameter.
          required: true
          type: string
          maxLength: 10
          x-aliyun-apigateway-parameter-demo: pathValue
          x-aliyun-apigateway-backend-name: pathParam
          x-aliyun-apigateway-backend-location: path
        - name: headParam
          in: header
          description: the header parameters.
          required: false
          type: string
          x-aliyun-apigateway-parameter-demo: headerValue
          x-aliyun-apigateway-backend-name: headParam
          x-aliyun-apigateway-backend-location: query
        - name: queryParam
          in: query
          description: the query parameters.
          required: false
          type: string
          x-aliyun-apigateway-parameter-demo: queryValue
          x-aliyun-apigateway-backend-name: queryParam
          x-aliyun-apigateway-backend-location: header
      responses:
        '200':
          description: success.
          x-aliyun-apigateway-response-messages: success
        '400':
          description: client error.
          x-aliyun-apigateway-response-messages: clent error
        '500':
          description: server error.
          x-aliyun-apigateway-response-messages: server error
      x-aliyun-apigateway-system-parameters:
        - backendName: testClientIp
          systemName: CaClientIp
          location: header
      x-aliyun-apigateway-constant-parameters:
        - backendName: constantparam
          location: header
          value: constantValue
          descriptoin: the constant parameters.
      x-aliyun-apigateway-api-name: export_1
      x-aliyun-apigateway-api-market-enable: false
      x-aliyun-apigateway-api-force-nonce-check: true
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-auth-type: APP
      x-aliyun-apigateway-api-enable-internet: true
      x-aliyun-apigateway-failed-demo: '{"result":"fail"}'
      x-aliyun-apigateway-success-demo: '{"result":"success"}'
      x-aliyun-apigateway-app-code-type: DEFAULT
      x-aliyun-apigateway-backend:
        body: good job
        statusCode: 200
        header:
          - name: test
            value: header1
        type: MOCK
  /export2/*:
    x-aliyun-apigateway-any-method:
      operationId: export_2
      description: test export job 1.
      x-aliyun-apigateway-api-market-enable: false
      x-aliyun-apigateway-api-force-nonce-check: false
      x-aliyun-apigateway-api-enable-internet: true
      x-aliyun-apigateway-parameter-handling: PASSTHROUGH
      x-aliyun-apigateway-auth-type: ANONYMOUS
      x-aliyun-apigateway-success-demo: '{"result":"success"}'
      x-aliyun-apigateway-failed-demo: '{"result":"fail"}'
      schemes:
        - http
        - https
      x-aliyun-apigateway-backend:
        body: good job
        statusCode: 200
        header:
          - name: test
            value: header1
        type: MOCK
      x-aliyun-apigateway-constant-parameters:
        - backendName: constantparam
          location: header
          value: constantValue
          descriptoin: the constant parameters.
      x-aliyun-apigateway-system-parameters:
        - backendName: testClientIp
          systemName: CaClientIp
          location: header
      responses:
        '200':
          description: success.
          briefMessage: success
          schema:
            $ref: testModel
        '400':
          description: client error.
          briefMessage: clent error
          schema:
            $ref: testModel
        '500':
          description: server error.
          briefMessage: server error
definitions:
  testModel:
    type: object
    required:
      - name
    properties:
      dogProject:
        type: object
        properties:
          name:
            type: string
            maxLength: 10
          id:
            type: integer
            format: int64
      name:
        type: string
        pattern: ^\d{3}-\d{2}-\d{4}$
      id:
        type: integer
        format: int64
      status:
        type: string