SwaggerファイルをインポートしてAPI Gateway拡張機能を持つAPIを作成する - API Gateway

Swaggerは、バックエンドサービスのAPIを定義および記述するために広く使用されている一連の仕様です。 API Gatewayでは、Swagger 2.0仕様に基づいてファイルをインポートできます。次の図に示すように、ImportSwagger操作を呼び出すか、コンソールを使用してSwagger準拠のデータをインポートできます。

API Gateway Swagger拡張は、Swagger 2.0に基づいています。 SwaggerベースのAPI定義を作成し、SwaggerファイルをAPI Gatewayコンソールにインポートして、一度に複数のAPIを作成または更新できます。 API GatewayはデフォルトでSwagger 2.0をサポートし、ほとんどのSwagger仕様バージョンと互換性があります。ただし、Swagger 2.0と他のSwagger仕様バージョンには実装の違いがあります。

このトピックでは、API Gateway Swagger拡張機能とその実装例について説明します。

説明

Swaggerのすべてのパラメータとその値は大文字と小文字を区別します。

1. Swaggerがサポートする拡張機能

Swaggerは、ネイティブのOperation Objectの拡張機能をサポートしています。拡張機能は、認証、パラメータマッピング、およびバックエンドサービスのための機能を提供するために使用されます。さらに、x-aliyun-apigateway-any-method拡張機能を使用して、API呼び出し元がAPIの呼び出しに使用できるHTTPメソッドを指定します。 API Gatewayに関連するすべての拡張機能は、x-aliyun-apigateway- で始まります。以下のセクションでは、拡張機能について説明します。

1.1 x-aliyun-apigateway-auth-type: authorization type

Operation Objectに適用され、API権限付与タイプを指定します。

有効値:

APP (デフォルト): APIを呼び出すためのIDとしてAlibaba Cloudアプリケーションを使用する必要があります。
匿名: すべてのユーザーは、アプリケーションをIDとして使用せずにAPIを呼び出すことができます。

例：

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-auth-type: ANONYMOUS
...

1.2 x-aliyun-apigateway-api-market-enable: Alibaba Cloud Marketplaceへのパブリッシング

Operation Objectに適用され、APIをAlibaba Cloud Marketplaceに公開するかどうかを指定します。

有効値:

true
false (デフォルト)

例：

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-api-market-enable: true
...

1.3 x-aliyun-apigateway-api-force-nonce-check: 強制的なnonce検証

Operation Objectに適用され、APIで強制ノンス検証を実行するかどうかを指定します。

有効値:

true
false (デフォルト)

例：

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-api-force-nonce-check: true
...

1.4 x-aliyun-apigateway-parameter-handling: API mapping

Operation Objectに適用され、リクエストパラメーターとバックエンドサービスパラメーター間のマッピングを指定します。 PASSTHROUGHを選択した場合、パラメーターオブジェクトはx-aliyun-apigateway-backend-locationおよびx-aliyun-apigateway-backend-nameをサポートしていません。

有効値:

PASSTHROUGH (デフォルト): リクエストパラメーターは、マッピングなしでバックエンドサービスに渡されます。
MAPPING: リクエストパラメータはバックエンドサービスパラメータにマッピングされます。

例：

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-parameter-handling: MAPPING
...

1.5 x-aliyun-apigateway-backend: バックエンドサービスタイプ

Operation Objectに適用され、バックエンドサービスタイプを指定します。特定のプロパティは、バックエンドサービスの種類によって異なります。詳細については、次の表を参照してください。

1.5.1 HTTP

このタイプは、バックエンドサービスに直接アクセスできるシナリオで使用されます。このタイプのバックエンドサービスのURLを直接設定できます。

プロパティの説明:

プロパティ	種類	説明
type	String	必須。値は HTTP です。
address	String	必須。バックエンドサービスのURL。
パス	String	オプションです。バックエンドサービスのパス。値は変数とすることができる。デフォルトでは、このプロパティの値はルートパスと同じです。
method	String	必須。バックエンド要求メソッド。
timeout	int	オプションです。デフォルトの値は 10,000 です。有効な値: 500〜30000。

例：

...
x-aliyun-apigateway-backend:
  type: HTTP
  address: 'http://www.aliyun.com'
  path: '/builtin/echo'
  method: get
  timeout: 10000
...

1.5.2 HTTP-VPC

バックエンドサービスが仮想プライベートクラウド (VPC) で実行されている場合、このタイプが使用されます。バックエンドサービスを設定するには、まずVPCアクセス許可を作成する必要があります。詳細については、VPC内のリソースをバックエンドサービスとしてAPIを作成する方法について説明しているトピックを参照してください。

プロパティの説明:

プロパティ	種類	説明
type	String	必須。値は HTTP-VPC です。
vpcAccessName	String	必須。バックエンドサービスへのアクセスに使用されるVPCアクセス許可の名前。
パス	String	オプションです。バックエンドサービスのパス。値は変数とすることができる。デフォルトでは、このプロパティの値はルートパスと同じです。
method	String	必須。バックエンド要求メソッド。
timeout	int	オプションです。デフォルトの値は 10,000 です。有効な値: 500〜30000。

例：

...
x-aliyun-apigateway-backend:
  type: HTTP_VPC
  vpcAccessName: vpcAccess1
  path: '/users/{userId}'
  method: GET
  timeout: 10000
...

1.5.3 FC

バックエンドサービスがFunction Computeの場合、バックエンドサービスタイプをFCに設定する必要があります。

プロパティの説明:

プロパティ	種類	説明
type	String	必須。値はFCである。
fcRegion	String	必須。 Function Computeサービスと関数がデプロイされているリージョン。
serviceName	String	必須。 Function Computeのサービスの名前。
functionName	String	必須。 function Computeの関数の名前。
arn	String	オプションです。 Function Computeのリソースアクセス管理 (RAM) 権限付与。

例：

...
x-aliyun-apigateway-backend:
  type: FC
  fcRegion: cn-shanghai
  serviceName: fcService
  functionName: fcFunction
  arn: acs:ram::111111111:role/aliyunapigatewayaccessingfcrole
...

1.5.4 モック

このタイプは、予想される結果をシミュレートするために使用されます。

プロパティの説明:

プロパティ	種類	説明
type	String	必須。値は MOCK です。
mockResult	String	必須。嘲笑された結果。
mockStatusCode	Integer	オプションです。
mockHeaders	ヘッダー	オプションです。

ヘッダーの説明:

プロパティ	種類	説明
name	String	必須/任意
value	String	必須/任意

例：

...
x-aliyun-apigateway-backend:
        type: MOCK
        mockResult: mock resul sample
        mockStatusCode: 200
        mockHeaders:
          - name: server
            value: mock
          - name: proxy
            value: GW
...

1.6 x-aliyun-apigateway-constant-parameters: constant parameters

Operation Objectに適用され、バックエンドサービスによって常に受信される定数パラメーターを定義します。バックエンドサービスに送信されるリクエストにこれらのパラメーターを含める必要はありません。

プロパティの説明:

プロパティ	種類	説明
backendName	String	必須。定数パラメーターの名前。
value	String	必須。定数パラメータの値。
場所	String	必須。定数パラメーターの場所。有効な値: queryとheader。
説明	String	オプションです。定数パラメーターの説明。

例：

      ...
      x-aliyun-apigateway-constant-parameters:
        - backendName: swaggerConstant
          value: swaggerConstant
          location: header
          description: description of swagger
      ...

1.7 x-aliyun-apigateway-system-parameters: バックエンドサービスのシステムパラメーター

Operation Objectに適用され、バックエンドサービスのシステムパラメーターを指定します。

プロパティの説明:

プロパティ	種類	説明
systemName	String	必須。システムパラメーターの名前。
backendName	String	必須。バックエンドサービスのシステムパラメーターのマッピングされた名前。
場所	String	必須。システムパラメータの場所。有効な値: queryとheader。

例：

    ...
    x-aliyun-apigateway-system-parameters:
        - systemName: CaAppId
          backendName: appId
          location: header
   ...

1.8 x-aliyun-apigateway-backend-location: backendパラメーターの場所

[パラメーターオブジェクト] に適用され、バックエンドサービスのリクエストパラメーターのマッピングされた場所を指定します。この拡張機能は、x-aliyun-apigateway-parameter-handlingがMAPPINGに設定されている場合にのみ有効です。

有効値:

パス
header
query
formData

例：

     ...
      parameters:
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
      ...

1.9 x-aliyun-apigateway-backend-name: backendパラメーター名

Parameter Objectに適用され、バックエンドサービスのリクエストパラメーターのマッピングされた名前を指定します。この拡張機能は、x-aliyun-apigateway-parameter-handlingがMAPPINGに設定されている場合にのみ有効です。

例：

      ...
      parameters:
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
      ...

1.10 x-aliyun-apigateway-query-schema: クエリパラメーターのスキーマ定義

Parameter Objectに適用され、クエリパラメータのスキーマを定義します。この拡張機能は、パラメーターがSTRING型で、クエリパラメーターとして定義されている場合に使用できます。

例：

      ...
      parameters:
        - name: event_info				
          in: query
          required: true
          type: string
          x-aliyun-apigateway-query-schema:
            $ref: "#/definitions/EvnetInfo"
      ...

1.11 x-aliyun-apigateway-any-method: ANYメソッド

Path Item Objectに適用され、APIの呼び出しに使用できるHTTPメソッドを指定します。

例：

...
paths:
  'path/':
     x-aliyun-apigateway-any-method:
     ...
...

1.12 x-aliyun-apigateway-app-code-type: AppCodeベースの単純認証

Operation Objectに適用され、APIがAppCodeベースの簡易認証をサポートするかどうかを指定します。

有効値:

デフォルト (デフォルト): AppCodeベースの簡易認証が有効になっています。
DISABLE: AppCodeベースの簡易認証は無効です。
HEADER: AppCodeはリクエストのヘッダーとして運ばれます。
HEADER_QUERY: AppCodeは、リクエスト内のヘッダーまたはQueryパラメーターとして運ばれます。

例：

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-app-code-type: HEADER
...

2. 互換性

API GatewayとSwaggerの仕様は、さまざまな方法でAPIを定義します。

2.1 パラメータタイプ

Swaggerのパラメータタイプ	API Gatewayのパラメータータイプ	サポートされている検証パラメーターとルール
タイプ: integer 形式: int32	Int	mininum maxnum
タイプ: integer 形式: int64	Long	mininum maxnum
type:number 形式: float	浮く	mininum maxnum
type:number 形式: double	Double	mininum maxnum
タイプ: string	String	maxLength enumValues pattern
type:boolean 形式: Boolean	Boolean	-

2.2 消費フィールドのサポート

Swagger設定ファイルにformDataパラメーターが含まれている場合は、消費フィールドを設定する必要があります。 API Gatewayでは、このフィールドはapplication/x-www-form-urlencodedにのみ設定できます。

consumes:
  - application/x-www-form-urlencoded

3. Swagger拡張機能の例

このセクションでは、API GatewayのSwagger拡張機能の4つの例を示します。例は、Swagger拡張機能のほぼすべての側面をカバーしています。 Swagger拡張機能に基づいてAPIを定義するときに、これらの例を参照できます。

説明

例は参考のためだけのものである。

3.1 バックエンドサービスタイプとしてHTTPを使用した例

swagger: '2.0'
basePath: /
info:
  version: '0.9'
  title: Aliyun Api Gateway Swagger Sample
schemes:
  - http
  - https
x-aliyun-apigateway-parameter-handling: MAPPING
x-aliyun-apigateway-api-market-enable: true
x-aliyun-apigateway-api-force-nonce-check: true
x-aliyun-apigateway-backend:
  type: HTTP
  address: 'http://www.aliyun.com'
  method: get
  timeout: 10000
paths:
  '/http/get/mapping/{userId}':
    get:
      operationId: case1
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-api-market-enable: true
      x-aliyun-apigateway-auth-type: ANONYMOUS
      parameters:
        - name: userId
          in: path
          required: true
          type: string
        - name: swaggerQuery
          in: query
          required: false
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
      x-aliyun-apigateway-constant-parameters:
        - backendName: swaggerConstant
          value: swaggerConstant
          location: header
          description: description of swagger
      x-aliyun-apigateway-system-parameters:
        - systemName: CaAppId
          backendName: appId
          location: header
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description
  '/echo/test/post/{userId}':
    post:
      operationId: testpost
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: HTTP
        address: 'http://www.aliyun.com'
        method: post
        timeout: 10000
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: userId
          required: true
          in: path
          type: string
        - name: swaggerQuery1
          in: query
          required: false
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          x-aliyun-apigateway-enum: 1,2,3
        - name: swaggerQuery2
          in: query
          required: false
          type: string
          x-aliyun-apigateway-backend-location: header
          x-aliyun-apigateway-backend-name: backendHeader
          x-aliyun-apigateway-query-schema:
            $ref: '#/definitions/AiGeneratePicQueryVO'
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
        - name: swaggerFormdata
          in: formData
          required: true
          type: string
      responses:
        '200':
          description: 200 description
          schema:
            $ref: '#/definitions/ResultOfGeneratePicturesVO'
        '400':
          description: 400 description
    x-aliyun-apigateway-any-method:
      operationId: case2
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: HTTP
        address: 'http://www.aliyun.com'
        path: '/builtin/echo/{abc}'
        method: post
        timeout: 10000
      parameters:
        - name: userId
          in: path
          required: false
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          x-aliyun-apigateway-backend-name: abc
          x-aliyun-apigateway-backend-location: path
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description
definitions:
  AiGeneratePicQueryVO:
    type: object
    properties:
      transactionId:
        type: string
        description: asynchronous task ID
  GeneratePictureVO:
    type: object
    properties:
      id:
        type: integer
        format: int64
        description: image ID
      name:
        type: string
        description: image name
  GeneratePicturesVO:
    type: object
    properties:
      failSize:
        type: integer
        format: int64
        description: number of failures
      list:
        type: array
        description: image list
        items:
          $ref: '#/definitions/GeneratePictureVO'
          title: GeneratePictureVO
      successSize:
        type: integer
        format: int32
        description: number of successes
      totalSize:
        type: number
        format: float
        description: total number of requests
  ResultOfGeneratePicturesVO:
    type: object
    properties:
      model:
        description: returned content
        $ref: '#/definitions/GeneratePicturesVO'
        title: GeneratePicturesVO
      requestId:
        type: string
        description: request ID

3.2 バックエンドサービスタイプとしてHTTP-VPCを使用する例

swagger: '2.0'
basePath: /
info:
  version: '0.9'
  title: Aliyun Api Gateway Swagger Sample
schemes:
  - http
  - https
paths:
  '/http/get/mapping/{userId}':
    get:
      operationId: case1
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: HTTP-VPC
        vpcAccessName: vpcName1
        path: '/builtin/echo/{userId}'
        method: get
        timeout: 10000
      parameters:
        - name: userId
          in: path
          required: true
          type: string
        - name: swaggerQuery
          in: query
          required: false
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description
  '/echo/test/post':
    post:
      operationId: testpost
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: HTTP-VPC
        vpcAccessName: vpcName2
        path: '/builtin/echo'
        method: post
        timeout: 10000
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: swaggerQuery1
          in: query
          required: false
          default: '123465'
          type: integer
          format: int32
          minimum: 0
          maximum: 100
        - name: swaggerQuery2
          in: query
          required: false
          type: string
          x-aliyun-apigateway-backend-location: header
          x-aliyun-apigateway-backend-name: backendHeader
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
        - name: swaggerFormdata
          in: formData
          required: true
          type: string
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description
    x-aliyun-apigateway-any-method:
      operationId: case2
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: PASSTHROUGH
      x-aliyun-apigateway-backend:
        type: HTTP-VPC
        vpcAccessName: vpcName3
        path: '/builtin/echo'
        method: post
        timeout: 10000
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description

3.3 バックエンドサービスタイプとしてFCを使用した例

swagger: '2.0'
basePath: /
info:
  version: '0.9'
  title: Aliyun Api Gateway Swagger Sample
schemes:
  - http
  - https
paths:
  '/http/get/mapping/{userId}':
    get:
      operationId: case1
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: FC
        fcRegion: cn-shanghai
        serviceName: fcService
        functionName: fcFunction
        arn: acs:ram::111111111:role/aliyunapigatewayaccessingfcrole
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description

3.4 バックエンドサービスタイプとしてMOCKを使用した例

swagger: '2.0'
basePath: /
info:
  version: '0.9'
  title: Aliyun Api Gateway Swagger Sample
schemes:
  - http
paths:
  '/mock/get/mapping/{userId}':
    get:
      operationId: case1
      schemes:
        - http
        - https
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: MOCK
        mockResult: mock resul sample
        mockStatusCode: 200
        mockHeaders:
          - name: server
            value: mock
          - name: proxy
            value: GW
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description

4. 使用上の注意

Swaggerのインポートに影響を与える可能性のある次の手順に注意してください。

4.1 拡張機能の範囲

特定のAPIに対して拡張機能が指定されていない場合、一部の拡張機能はグローバル値を使用します。特定のAPIに対して個別に異なる値を指定した場合は、個別に指定した値が有効になります。次のアイテムは、それらの拡張機能の一覧です。

x-aliyun-apigateway-backend
x-aliyun-apigateway-api-market-enable
x-aliyun-apigateway-api-force-nonce-check
x-aliyun-apigateway-parameter-handling
x-aliyun-apigateway-auth-type

4.2 Swaggerの定義フィールドの説明

API Gatewayは、Swaggerインポートのモデル定義をサポートします。ただし、モデルの定義はSwagger仕様とは異なります。 モデル定義は、SDKの生成に使用されます。 Swaggerの仕様には、次の制限があります。

schemaタグは $ref型のみをサポートします。
[定義] フィールドのモデルは、オブジェクト型のモデル定義のみをサポートします。
配列は、定義フィールドのモデルで定義されています。参照に $refを使用する場合は、titleタグが必要です。配列タイプを指定した場合は, SDKの生成時に配列リストも生成されます。