Swagger のインポートによる API の作成 - API Gateway - Alibaba Cloud ドキュメントセンター

API Gateway の Swagger 拡張は、Swagger 2.0 に基づいています。これらの拡張機能を使用して API の Swagger 定義を作成し、Swagger ファイルを API Gateway にインポートすると、API を一括で作成または更新できます。 API Gateway は Swagger 2.0 用に事前設定されており、Swagger 仕様のほとんどをサポートしていますが、いくつかの相違点があります。

Swagger のインポート方法

Swagger は API 定義を記述するための仕様です。バックエンドアプリケーションサービスの API を定義および記述するために広く使用されています。 API Gateway では、Swagger 2.0 ファイルをインポートして API を作成できます。 ImportSwagger API を呼び出すか、コンソールで操作を実行できます。

API Gateway コンソールの左側メニューで、 [API 管理] > [API リスト] を選択します。次に、ページの右上隅にある [Swagger のインポート] をクリックします。

以降のセクションでは、API Gateway の Swagger 拡張について説明し、拡張機能の使用方法を例を用いて示します。

重要

Swagger のすべてのパラメーターと値は、大文字と小文字が区別されます。

Swagger 拡張

API Gateway の Swagger 拡張は、主に Swagger ネイティブのオペレーションオブジェクトを拡張し、認証、パラメーターマッピング、バックエンドサービスの機能を追加します。あらゆるメソッドの HTTP リクエストをキャプチャするために、ANY メソッドの拡張機能も提供されています。すべての拡張機能は x-aliyun-apigateway- で始まります。以降のセクションでは、各拡張機能について説明します。

グローバルスコープのサポート

次の拡張機能は、グローバルスコープでの定義に対応しています。拡張機能が独自のスコープで定義されていない場合は、グローバルスコープで定義されている値が自動的に適用されます。拡張機能が独自のスコープで定義されている場合は、そのスコープの値が優先されます。

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

`x-aliyun-apigateway-auth-type`：認可タイプ

x-aliyun-apigateway-auth-type はオペレーションオブジェクトに適用され、API の認可タイプを指定します。

有効値：

APP (デフォルト)：Alibaba Cloud API Gateway による APP 認証。
ANONYMOUS：匿名アクセス。
例：

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

`x-aliyun-apigateway-api-market-enable`：Alibaba Cloud Marketplace のサポート

x-aliyun-apigateway-api-market-enable はオペレーションオブジェクトに適用され、API を Alibaba Cloud Marketplace に公開できるかどうかを指定します。

有効値：

true
false (デフォルト)
例：

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

`x-aliyun-apigateway-api-force-nonce-check`：NONCE チェック

x-aliyun-apigateway-api-force-nonce-check はオペレーションオブジェクトに適用され、API の NONCE チェックを強制するかどうかを指定します。

有効値：

true
false (デフォルト)
例：

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

`x-aliyun-apigateway-parameter-handling`：パラメーターマッピング

x-aliyun-apigateway-parameter-handling はオペレーションオブジェクトに適用され、リクエストパラメーターがバックエンドサービスのパラメーターにどのようにマッピングされるかを指定します。マッピング関係が PASSTHROUGH に設定されている場合、パラメーターオブジェクトは x-aliyun-apigateway-backend-location プロパティと x-aliyun-apigateway-backend-name プロパティには対応していません。

有効値：

PASSTHROUGH (デフォルト)：リクエストパラメーターをパススルーします。
MAPPING：リクエストパラメーターをマッピングします。
例：

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

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

x-aliyun-apigateway-backend はオペレーションオブジェクトに適用され、バックエンドサービスに関する情報を設定します。使用可能なプロパティは、以降のセクションで説明するように、バックエンドサービスのタイプによって異なります。

バックエンドサービスタイプ：HTTP

HTTP バックエンドサービスタイプを使用して、バックエンドサービスのアドレスを直接設定します。このタイプは通常、バックエンドのアドレスに直接アクセスできる場合に使用されます。

次の表に、HTTP バックエンドサービスタイプのプロパティを示します。

プロパティ	タイプ	説明
type	string	必須。値は `HTTP` です。
address	string	必須。バックエンドサービスのアドレスを指定します。
path	string	任意。バックエンドサービスのパスを指定します。パス変数がサポートされています。デフォルトでは、この値はルートパスと同じです。
method	string	必須。バックエンドリクエストのメソッドです。
timeout	int	任意。デフォルト値：10000。有効値：500～30000。

例：

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

バックエンドサービスタイプ：HTTP-VPC

HTTP-VPC バックエンドサービスタイプは、バックエンドサービスが VPC 内に存在する場合に使用します。まず VPC アクセス権限を作成し、その名前で権限をインポートする必要があります。詳細については、「VPC 内のリソースをバックエンドサービスとして使用する API の作成」をご参照ください。

次の表に、HTTP-VPC バックエンドサービスタイプのプロパティを示します。

プロパティ	タイプ	説明
type	string	必須。値は `HTTP-VPC` です。
vpcAccessName	string	必須。バックエンドサービスが使用する VPC アクセス設定の名前。
path	string	任意。バックエンドサービスのパスを指定します。パス変数がサポートされています。デフォルトでは、この値はルートパスと同じです。
method	string	必須。バックエンドリクエストのメソッドです。
timeout	int	任意。デフォルト値：10000。有効値：500～30000。

例：

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

バックエンドサービスタイプ：FC

API Gateway のバックエンドサービスが Function Compute の場合は、FC バックエンドサービスタイプを使用します。

次の表に、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
...

バックエンドサービスタイプ：MOCK

MOCK バックエンドサービスタイプを使用して、事前定義したレスポンスをシミュレートします。

次の表に、MOCK バックエンドサービスタイプのプロパティを示します。

プロパティ	タイプ	説明
type	string	必須。値は `MOCK` です。
mockResult	string	必須。モックのレスポンスです。
mockStatusCode	integer	任意。
mockHeaders	Header	任意。

次の表に、Header タイプのプロパティを示します。

プロパティ	タイプ	説明
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
...

`x-aliyun-apigateway-constant-parameters`：定数パラメーター

x-aliyun-apigateway-constant-parameters はオペレーションオブジェクトに適用され、バックエンドサービスの定数パラメーターを定義します。

次の表に、定数パラメーターのプロパティを示します。

プロパティ	タイプ	説明
backendName	string	必須。バックエンドパラメーターの名前です。
value	string	必須。定数値です。
location	string	必須。定数パラメーターが格納される場所。有効値：`query` および `header`。
description	string	任意。定数の説明。

例：

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

`x-aliyun-apigateway-system-parameters`：システムパラメーター

x-aliyun-apigateway-system-parameters はオペレーションオブジェクトに適用され、API のバックエンドサービスのシステムパラメーターを定義します。

次の表に、バックエンドシステムパラメーターのプロパティを示します。

プロパティ	タイプ	説明
systemName	string	必須。システムパラメーターの名前です。
backendName	string	必須。バックエンドパラメーターの名前です。
location	string	必須。システムパラメーターが格納される場所。有効値：`query` および `header`。

例：

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

`x-aliyun-apigateway-backend-location`：バックエンドパラメーターの場所

x-aliyun-apigateway-backend-location はパラメーターオブジェクトに適用され、パラメーターマッピング後のバックエンドサービスリクエストにおけるパラメーターの場所を指定します。このプロパティは、x-aliyun-apigateway-parameter-handling: MAPPING が設定されている場合にのみ有効です。

有効値：

path
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
...

`x-aliyun-apigateway-backend-name`：バックエンドパラメーター名

x-aliyun-apigateway-backend-name はパラメーターオブジェクトに適用され、パラメーターマッピング後のバックエンドサービスリクエストにおけるパラメーターの名前を指定します。このプロパティは、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
...

`x-aliyun-apigateway-query-schema`：クエリパラメーターのスキーマ

x-aliyun-apigateway-query-schema はパラメーターオブジェクトに適用され、クエリパラメーターのモデルを定義します。この拡張機能は、パラメーターが String 型で、クエリパラメーターとして定義されている場合に使用できます。

例：

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

`x-aliyun-apigateway-any-method`：ANY メソッド

x-aliyun-apigateway-any-method はパスアイテムオブジェクトに適用され、API が任意のタイプの HTTP リクエストを受け入れられるようにします。

例：

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

`x-aliyun-apigateway-app-code-type`：AppCode 認証

x-aliyun-apigateway-app-code-type はオペレーションオブジェクトに適用され、API が AppCode 認証に対応するかどうかを指定します。

有効値：

DEFAULT (デフォルト)
DISABLE：AppCode 認証を無効にします。
HEADER：リクエストヘッダーで AppCode を渡します。
HEADER_QUERY：リクエストヘッダーまたはクエリパラメーターで AppCode を渡します。
例：

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

Swagger 仕様との違い

API Gateway と Swagger 仕様は、API を定義する際に次の点で異なります。これらの違いは、Swagger のインポート機能の使用方法に直接影響します。

Swagger パラメータータイプと元の API Gateway タイプのマッピング

Swagger タイプ	API Gateway タイプ	サポートされる検証パラメーターとルール
`type: integer`、`format: int32`	Int	`minimum`、`maximum`
`type: integer`、`format: int64`	Long	`minimum`、`maximum`
`type: number`、`format: float`	Float	`minimum`、`maximum`
`type: number`、`format: double`	Double	`minimum`、`maximum`
`type: string`	String	`maxLength`、`enumValues`、`pattern`
`type: boolean`、`format: boolean`	Boolean	-

consumes フィールドのサポート

Swagger 設定ファイルに formData パラメーターが含まれている場合は、consumes ノードを設定する必要があります。 API Gateway は現在、application/x-www-form-urlencoded タイプにのみ対応しています。

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

Swagger 定義の制限

Swagger のインポートはモデル定義に対応していますが、実装は元の Swagger 仕様とは異なります。モデル定義は、主にソフトウェア開発キット (SDK) を生成するために使用されます。したがって、元の Swagger 仕様に加えて、次の制限があります。

Swagger の schema タグは、$ref タイプにのみ対応します。
Swagger definitions セクションのモデルは、object タイプのモデル定義にのみ対応します。
Swagger definitions セクションのモデルに配列定義が含まれている場合、$ref 参照は title タグと一緒に使用する必要があります。デフォルトでは、SDK の生成中に配列タイプは ArrayList として生成されます。

Swagger の例

次の例は、API Gateway の Swagger 拡張機能を使用した完全な Swagger 定義です。独自の API を定義する際の参考にしてください。

説明

この例は参考用です。

Swagger の例：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: swagger の説明
      x-aliyun-apigateway-system-parameters:
        - systemName: CaAppId
          backendName: appId
          location: header
      responses:
        '200':
          description: 200 の説明
        '400':
          description: 400 の説明
  '/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
        - 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 の説明
          schema:
            $ref: '#/definitions/ResultOfGeneratePicturesVO'
        '400':
          description: 400 の説明
    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 の説明
        '400':
          description: 400 の説明
definitions:
  AiGeneratePicQueryVO:
    type: object
    properties:
      transactionId:
        type: string
        description: 非同期タスク ID
  GeneratePictureVO:
    type: object
    properties:
      id:
        type: integer
        format: int64
        description: 画像 ID
      name:
        type: string
        description: 画像名
  GeneratePicturesVO:
    type: object
    properties:
      failSize:
        type: integer
        format: int64
        description: 失敗数
      list:
        type: array
        description: 画像リスト
        items:
          $ref: '#/definitions/GeneratePictureVO'
          title: GeneratePictureVO
      successSize:
        type: integer
        format: int64
        description: 成功数
      totalSize:
        type: integer
        format: int64
        description: リクエスト総数
  ResultOfGeneratePicturesVO:
    type: object
    properties:
      model:
        description: レスポンス内容
        $ref: '#/definitions/GeneratePicturesVO'
        title: GeneratePicturesVO
      requestId:
        type: string
        description: リクエスト ID

Swagger の例：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 の説明
        '400':
          description: 400 の説明
  '/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 の説明
        '400':
          description: 400 の説明
    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 の説明
        '400':
          description: 400 の説明

Swagger の例：Function Compute バックエンドサービス

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 の説明
        '400':
          description: 400 の説明

Swagger の例：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 の説明
        '400':
          description: 400 の説明

Swagger のインポート方法

Swagger 拡張

グローバルスコープのサポート

x-aliyun-apigateway-auth-type：認可タイプ

x-aliyun-apigateway-api-market-enable：Alibaba Cloud Marketplace のサポート

x-aliyun-apigateway-api-force-nonce-check：NONCE チェック

x-aliyun-apigateway-parameter-handling：パラメーターマッピング

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

バックエンドサービスタイプ：HTTP

バックエンドサービスタイプ：HTTP-VPC

バックエンドサービスタイプ：FC

バックエンドサービスタイプ：MOCK

x-aliyun-apigateway-constant-parameters：定数パラメーター

x-aliyun-apigateway-system-parameters：システムパラメーター

x-aliyun-apigateway-backend-location：バックエンドパラメーターの場所

x-aliyun-apigateway-backend-name：バックエンドパラメーター名

x-aliyun-apigateway-query-schema：クエリパラメーターのスキーマ

x-aliyun-apigateway-any-method：ANY メソッド

x-aliyun-apigateway-app-code-type：AppCode 認証

Swagger 仕様との違い

Swagger パラメータータイプと元の API Gateway タイプのマッピング

consumes フィールドのサポート

Swagger 定義の制限

Swagger の例

Swagger の例：HTTP バックエンドサービス

Swagger の例：HTTP-VPC バックエンドサービス

Swagger の例：Function Compute バックエンドサービス

Swagger の例：MOCK バックエンドサービス

`x-aliyun-apigateway-auth-type`：認可タイプ

`x-aliyun-apigateway-api-market-enable`：Alibaba Cloud Marketplace のサポート

`x-aliyun-apigateway-api-force-nonce-check`：NONCE チェック

`x-aliyun-apigateway-parameter-handling`：パラメーターマッピング

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

`x-aliyun-apigateway-constant-parameters`：定数パラメーター

`x-aliyun-apigateway-system-parameters`：システムパラメーター

`x-aliyun-apigateway-backend-location`：バックエンドパラメーターの場所

`x-aliyun-apigateway-backend-name`：バックエンドパラメーター名

`x-aliyun-apigateway-query-schema`：クエリパラメーターのスキーマ

`x-aliyun-apigateway-any-method`：ANY メソッド

`x-aliyun-apigateway-app-code-type`：AppCode 認証