一度に複数のOAS準拠APIをインポートする方法 - API Gateway

API Gatewayを使用すると、OpenAPI Specification (OAS) 2.0または3.0標準に準拠したAPI定義をインポートできます。 OASの詳細については、「OpenAPI仕様」をご参照ください。 OAS準拠のAPI定義をインポートするか、またはAPI Gateway拡張機能を含むOAS準拠のAPI定義をインポートできます。

OAS準拠のAPI定義のインポート

プロセス:

APIをインポートするAPIグループを指定し、グローバル設定を設定します。
OAS 2.0準拠またはOAS-3.0準拠のAPI定義を入力します。
API定義を事前チェックし、事前チェックの結果に基づいて問題を修正します。
API定義をインポートします。

API定義がインポートされると、指定されたAPIグループにAPIが作成されます。次に、選択した環境にAPIを公開し、APIをデバッグできます。詳細については、「APIのデバッグ」をご参照ください。

API Gatewayコンソールにログインします。
左側のナビゲーションウィンドウで、[APIの管理] > [API] を選択します。
[API] ページで、[Swagger準拠のデータのインポート] をクリックします。

[メモ] ダイアログボックスで、[標準OAS] をクリックして、Swagger準拠のデータのインポートページに移動します。

[基本情報] セクションで、次のパラメーターを設定します。

パラメーター	説明
グループにインポート	APIをインポートするAPIグループを指定します。重要 APIグループのベースパスは、OAS準拠のAPI定義のベースパスと同じである必要があります。それ以外の場合、定義のインポートに失敗します。 APIグループのベースパスの詳細については、「APIグループの作成」をご参照ください。 OASのベースパスの詳細については、「Swagger Object」をご参照ください。
上書き	チェックボックスをオンにすると、リクエストパスがHTTPリクエストと競合すると、既存のAPIが上書きされます。チェックボックスを選択せず、リクエストパスがHTTPリクエストと競合する場合、APIが既に存在することを示すエラーメッセージが返されます。
API定义バージョン	OAS 2.0とOAS 3.0がサポートされています。

(オプションの) グローバル設定セクションで、APIのグローバル設定を設定します。

パラメーター	説明
バックエンドサービス	API Gatewayで作成されるHTTP/HTTPS、VPC、混合、またはサービスの検出タイプのバックエンドサービスを指定します。デフォルト値はMockです。詳細については、「バックエンドサービスを使用したAPIの作成と管理」をご参照ください。
リクエストモード	このパラメータをパススルーまたはマップ (不明なパラメータをフィルタアウト) に設定します。デフォルト値はパススルーです。説明パススルー要求モードを使用する場合、pathパラメーターのみがインポートされます。 API Gatewayは、query、header、formdata、bodyパラメーターなど、その他のパラメーターを無視します。
発信者認証	このパラメーターをAlibaba Cloudアプリまたは認証なしに設定します。デフォルト値はAlibaba Cloud Appです。説明バックエンドサービス、リクエストモード、および呼び出し元認証は、すべてのAPIで有効になるグローバル設定です。 API Gatewayでサポートされている拡張機能を使用してOAS 2.0-complinant API定義で設定を宣言する場合、設定はOAS 2.0-complinant API定義、OASグローバル定義、およびAPI Gatewayのオプションのグローバル設定の順序で優先されます。拡張機能の詳細については、このトピックの「API Gateway拡張機能を含むOAS準拠のAPI定義のインポート」を参照してください。 AppCode認証: Caller AuthenticationをAlibaba Cloud Appに設定した場合、デフォルト値はAppCode認証を無効にします。署名アルゴリズム: デフォルト値はHMAC_SHA256です。

[API定義] セクションで、OAS 2.0-complinant API定義を入力し、次のいずれかのインポート方法を指定します。
重要
各メソッドでは、最大100のAPI定義を同時にインポートできます。
1. テキスト: API定義をYAMLまたはJSON形式で入力します。 API定義の長さは最大256 KBです。
2. OSS URL: API定義が保存されているObject Storage Service (OSS) オブジェクトのURLを入力します。オブジェクトはJSONまたはYAML形式である必要があります。オブジェクトURLは匿名アクセスをサポートする必要があります。オブジェクトサイズに制限はありません。

API定義の他のパラメーターのデフォルト設定を変更するかどうかを決定します。これらのパラメーターは、API定義をインポートするときに設定されますが、Swagger準拠のデータのインポートページでは提供されません。次の表に、パラメーターを示します。

パラメーター	説明
リプレイ防止保護	デフォルトでは、この機能は無効化されています。
インターネットアクセスの禁止	デフォルトでは、この機能は無効化されています。
Alibaba Cloud MarketplaceへのAPI公開を許可する	デフォルトでは、この機能は無効化されています。

[事前チェック] をクリックします。 API Gatewayは、インポートするデータに対してドライランを実行し、OAS準拠のAPI定義のAPI定義とモデル定義、警告、およびエラーを返します。
説明
警告: API定義をインポートする前に、警告を無視できます。この場合、警告を含むAPI定義は無視されます。
エラー: エラーを修正する必要があります。それ以外の場合、例外がスローされます。
エラーや警告が存在しないことを確認し、Swagger準拠のデータのインポートをクリックしてAPIをインポートします。このプロセスには時間がかかる場合があります。インポートが完了する前にブラウザを閉じないでください。
APIのインポート後、APIのインポート結果を表示できます。

OAS 2.0-complinant API定義とAPI Gateway API定義のパラメーター間のマッピング

説明

ここでは、API GatewayのAPI定義のパラメーターにマッピングできるOAS 2.0対応のAPI定義のパラメーターについてのみ説明します。 OAS 2.0準拠API定義のパラメーターをAPI Gatewayにマップできない場合、APIのインポートは影響を受けません。

Swaggerオブジェクト
1. BasePath: APIグループのベースパス。 API定義をインポートすると、API Gatewayは、API定義のベースパスがAPIグループのベースパスと同じかどうかを確認します。
2. スキーム: API定義のリクエストプロトコル。
Pathアイテムオブジェクト
1. Path: API定義のリクエストパス。
2. メソッド: API定義のリクエストメソッド。有効な値: GET、POST、PUT、HEAD、DELETE、PATCH、およびOPTIONS。
操作オブジェクト
1. Summary: API定義の説明。
2. OperationId: API定義に対応するAPIの名前。拡張フィールドx-aliyun-apigateway-api-nameが存在する場合、拡張フィールドの名前がAPIの名前として使用されます。
3. スキーム: API定義のリクエストプロトコル。オペレーションオブジェクトのスキームは、Swaggerオブジェクトのスキームよりも優先されます。
パラメータオブジェクト
1. Name: API定義のリクエストパラメーターの名前。
2. In: API定義内のリクエストパラメーターの場所。有効な値: path、query、head、formdata。
3. 説明: API定義のリクエストパラメーターの説明。
4. 必須: API定義のリクエストパラメーターが必要かどうかを指定します。
5. Type: API定義のリクエストパラメーターのタイプ。
  1. Inをquery、path、headに設定した場合の有効な値: string、number、integer、boolean、およびarray。
  2. Inをformdataに設定した場合の有効な値: string、number、integer、boolean、array、file。
6. Format: API定義のリクエストパラメーターの形式。タイプよりもフォーマットが優先されます。
  次の表に、OASのパラメーター型とAPI Gatewayのパラメーター型の間のマッピングを示します。
  OASのパラメータタイプ
  API Gatewayのパラメータータイプ
  String
  String
  Boolean
  Boolean
  配列
  配列
  Int32
  Int
  Int64
  Long
  Double
  Double
  浮く
  浮く
  ファイル
  ファイル
  説明
  1. API定義にパススルーリクエストモードを使用する場合、パスパラメーターのみがAPI定義にインポートされます。 API Gatewayは、query、header、formdata、bodyパラメーターなど、その他のパラメーターを無視します。
  2. API定義にパススルーリクエストモードを使用し、API Gateway拡張機能を使用しない場合は、API定義のリクエストパラメーターとバックエンドサービスのリクエストメソッド、リクエストパス、パラメーター定義に同じ値が指定されていることを確認してください。
  3. リクエスト本文のパラメーターを参照すると、ドキュメントの生成時にパラメーターが表示されますが、API GatewayのAPI定義には表示されません。
応答オブジェクト
1. HTTPステータスコード: API定义で定义したレスポンスのエラーコード定义に含まれるHTTPステータスコード。
2. 説明: API定義のサンプルレスポンスのエラーコード定義の説明。
3. スキーマ: API定義で定義されたレスポンスのエラーコード定義に含まれるモデル。
定義オブジェクト
API定義内のオブジェクト。 API定義をインポートすると、API Gatewayは指定したAPIグループにモデルを作成します。 [APIグループ] ページで、APIグループの [アクション] 列の [モデルの管理] をクリックして、モデル定義を表示できます。

次のサンプルコードは、この機能に慣れるのに役立つOAS 2.0のAPI定義を定義する方法の例を示しています。この例では、Swagger PetstoreのAPI定義を使用します。

swagger: "2.0"
info:
  version: "1.0.0"
  title: "Swagger Petstore 2.0"
basePath: "/"
schemes:
- "https"
- "http"
paths:
  /pet/findByStatus:
    get:
      tags:
      - "pet"
      summary: "Finds Pets by status"
      operationId: "findPetsByStatus"
      parameters:
      - name: "status"
        in: "query"
        required: true
        type: "array"
        items:
          type: "string"
          enum:
          - "available"
          - "pending"
          - "sold"
          default: "available"
        collectionFormat: "multi"
      responses:
        "200":
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Pet"
        "400":
          description: "Invalid status value"
definitions:
  Category:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"
  Tag:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"
  Pet:
    type: "object"
    required:
    - "name"
    - "photoUrls"
    properties:
      id:
        type: "integer"
        format: "int64"
      category:
        $ref: "#/definitions/Category"
      name:
        type: "string"
        example: "doggie"
      photoUrls:
        type: "array"
        items:
          type: "string"
      tags:
        type: "array"
        items:
          $ref: "#/definitions/Tag"
      status:
        type: "string"
        description: "pet status in the store"
        enum:
        - "available"
        - "pending"
        - "sold"

OAS 3.0-complinant API定義とAPI Gateway API定義のパラメーター間のマッピング

説明

このセクションでは、OAS 3.0準拠のAPI定義とAPI Gateway API定義の間でマップされたフィールドについて説明します。マッピングされていないフィールドはAPIインポートに影響しません。

Pathアイテムオブジェクト
1. Path: API定義のリクエストパス。
2. メソッド: API定義のリクエストメソッド。有効な値: GET、POST、PUT、HEAD、DELETE、PATCH、およびOPTIONS。
操作オブジェクト
1. Summary: API定義の説明。
2. OperationId: API定義に対応するAPIの名前。拡張フィールドx-aliyun-apigateway-api-nameが存在する場合、拡張フィールドの名前がAPIの名前として使用されます。
パラメータオブジェクト
1. Name: API定義のリクエストパラメーターの名前。
2. In: API定義内のリクエストパラメーターの場所。有効な値: path、query、head、formdata。
3. 必須: API定義のリクエストパラメーターが必要かどうかを指定します。
スキーマオブジェクト
1. 説明: API定義のリクエストパラメーターの説明。
2. Type: API定義のリクエストパラメーターのタイプ。
  1. Inをquery、path、headに設定した場合の有効な値: string、number、integer、boolean、およびarray。
  2. Inをformdataに設定した場合の有効な値: string、number、integer、boolean、array、file。
3. Format: API定義のリクエストパラメーターの形式。タイプよりもフォーマットが優先されます。
要求本文オブジェクト
1. Content
  1. application/x-www-form-urlencoded: API定義のformdataパラメーター。
  2. application/json: この項目で定義されているオブジェクトの場合、API Gatewayはインポート時にグループ内にモデルを作成します。モデル定義を表示するには、グループリストのグループを含む行の [アクション] 列の [モデルの管理] をクリックします。
応答オブジェクト
1. HTTPステータスコード: API定义で定义したレスポンスのエラーコード定义に含まれるHTTPステータスコード。
2. 説明: API定義のサンプルレスポンスのエラーコード定義の説明。
3. Content: API定義で定義されたレスポンスのエラーコード定義のモデル。

次の例は、OAS 3.0準拠の定義を示しています。この例では、PetStoreの定義が使用されます。

openapi: 3.0.0
info:
  title: Swagger Petstore - OpenAPI 3.0
  version: 1.0.0
paths:
  /pet:
    put:
      tags:
        - pet
      summary: Update an existing pet
      description: Update an existing pet by Id
      operationId: updatePet
      requestBody:
        description: Update an existent pet in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Pet'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'          
        '400':
          description: Invalid ID supplied
        '404':
          description: Pet not found
        '422':
          description: Validation exception
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: Add a new pet to the store
      operationId: addPet
      requestBody:
        description: Create a new pet in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Pet'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '400':
          description: Invalid input
        '422':
          description: Validation exception
  /pet/findByStatus:
    get:
      tags:
        - pet
      summary: Finds Pets by status
      description: Multiple status values can be provided with comma separated strings
      operationId: findPetsByStatus
      parameters:
        - name: status
          in: query
          description: Status values that need to be considered for filter
          required: false
          explode: true
          schema:
            type: string
            default: available
            enum:
              - available
              - pending
              - sold
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        '400':
          description: Invalid status value
components:
  schemas:
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: Dogs
      xml:
        name: category
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
      xml:
        name: tag
    Pet:
      required:
        - name
        - photoUrls
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: doggie
        category:
          $ref: '#/components/schemas/Category'
        photoUrls:
          type: array
          xml:
            wrapped: true
          items:
            type: string
            xml:
              name: photoUrl
        tags:
          type: array
          xml:
            wrapped: true
          items:
            $ref: '#/components/schemas/Tag'
        status:
          type: string
          description: pet status in the store
          enum:
            - available
            - pending
            - sold
      xml:
        name: pet

OAS 2.0のインポート-API Gateway拡張を含む包括的なAPI定義

詳細については、「OASに基づくAPIのエクスポート」をご参照ください。

OASのパラメータタイプ	API Gatewayのパラメータータイプ
String	String
Boolean	Boolean
配列	配列
Int32	Int
Int64	Long
Double	Double
浮く	浮く
ファイル	ファイル