Swagger は、API 定義を記述するための仕様で、バックエンドサービス用の API の定義と記述に広く使用されています。Swagger 2.0 ファイルを API Gateway にインポートすると、API を作成できます。詳細は、「ImportSwagger による API の作成」をご参照ください。または、次の図のようにコンソールで操作してください。
API Gateway Swagger 拡張機能は、Swagger 2.0 に基づいています。API エンティティの Swagger 定義を作成し、API エンティティを一括で作成または更新するための Swagger ファイルを API Gateway にインポートすることができます。API Gateway は、デフォルトでは Swagger 2.0 をサポートしていますが、ほとんどの Swagger 仕様と互換性があります。ただし、これらの Swagger のバージョンとの間に、いくつかの違いがあります。詳細については、「互換性」をご参照ください。
このトピックでは、Swagger に基づく API Gateway 拡張機能について説明し、実際の記述例を示します。
注:Swagger のすべてのパラメーターと値は、大文字と小文字を区別します。
1.Swagger 拡張機能
Swagger 拡張機能は、ネイティブ Swagger Operation Object を拡張するために使用され、認証、パラメーターマッピング、バックエンドサービスなどの機能を提供します。また、これらの拡張機能には、HTTP メソッドで送信されたリクエストに対応するため、ANY メソッドの処理がサポートされています。後述するように、すべての拡張機能は、x-aliyun-apigateway-
で始まります。
1.1 x-aliyun-apigateway-auth-type: 認証タイプ
認証タイプは、Operation Object に適用されます。この拡張機能を使用して、API 認証タイプを指定します。
値の範囲:
- APP (デフォルト):API Gateway のアプリケーション認証。
- ANONYMOUS:匿名
例:
...
paths:
'path/':
get:
x-aliyun-apigateway-auth-type: ANONYMOUS
...
1.2 x-aliyun-apigateway-paramater-handling: API マッピング関係
Operation Object に適用される API マッピング関係を使用して、リクエストパラメーターとバックエンドサービスパラメーターとのマッピング関係を指定します。PASSTHROUGH をマッピング関係として選択した場合、Parameter Objectは、x-aliyun-apigateway-backend-location
プロパティと x-aliyun-apigateway-backend-name
プロパティをサポートしません。
値の範囲:
- PASSTHROUGH (デフォルト):リクエストパラメーターパススルー。
- MAPPING:リクエストパラメータマッピング。
例:
...
paths:
'path/':
get:
x-aliyun-apigateway-paramater-handling: MAPPING
...
1.3 x-aliyun-apigateway-backend:バックエンドタイプ
Operation Object に適用されるバックエンドタイプです。このパラメーターを使用して、バックエンドサービス情報を指定します。次に示すように、バックエンドサービスタイプに応じて、固有のプロパティがあります。
1.3.1 バックエンドサービスタイプ:HTTP
HTTP バックエンドタイプは、バックエンドサービスに直接アクセスするサービスアドレスを設定するために使用されます。
プロパティの説明:
プロパティ名 | 型 | 説明 |
---|---|---|
type | string | 必須。値は HTTP です。 |
address | string | 必須。バックエンドサービスのアドレス。 |
path | string | 必須。バックエンドサービスのパス。パス変数をサポートします。 |
method | string | 必須。バックエンドリクエストメソッド。 |
timeout | int | オプション。デフォルト値は 10,000 です。プロパティ値の範囲は、500〜30000 です。 |
例:
...
x-aliyun-apigateway-backend:
type: HTTP
address: http://10.10.100.2:8000
path: "/users/{userId}"
method: GET
timeout: 7,000
...
1.3.2 バックエンドサービスタイプ:HTTP-VPC
HTTP-VPC バックエンドタイプは、バックエンドサービスが VPC ネットワークで実行されている場合にデプロイされます。VPC アクセスを作成し、その後、VPC アクセス名を使用してインポートする必要があります。
プロパティの説明:
プロパティ名 | 型 | 説明 |
---|---|---|
type | string | 必須。値は HTTP-VPC です。 |
vpcAccessName | string | 必須。バックエンドサービスで使用される VPC ネットワーク名。 |
path | string | 必須。バックエンドサービスのパスを指定します。パス変数をサポートします。 |
method | string | 必須。バックエンドリクエストメソッド。 |
timeout | int | オプション。デフォルト値は 10,000 です。プロパティ値の範囲は、500〜30000 です。 |
例:
...
x-aliyun-apigateway-backend:
type: HTTP_VPC
vpcAccessName: vpcAccess1
path: "/users/{userId}"
method: GET
timeout: 10,000
...
1.3.3 バックエンドサービスタイプ:FC
FC バックエンドタイプは、Function Compute サービスにアクセスするためのサービスアドレスを設定するために使用されます。
プロパティの説明:
プロパティ名 | 型 | 説明 |
---|---|---|
type | string | 必須。値は FC です。 |
fcRegion | string | 必須。FC のリージョン。 |
serviceName | string | 必須。FC のサービス名。 |
functionName | string | 必須。FC の関数名 |
arn | string | 必須。FC の Arn。 |
例:
...
x-aliyun-apigateway-backend:
type: FC
fcRegion: cn-shanghai
serviceName: fcService
functionName: fcFunction
arn: acs:ram::111111111:role/aliyunapigatewayaccessingfcrole
...
1.3.4 バックエンドサービスタイプ:MOCK
MOCK バックエンドタイプは、 デフォルトのレスポンスを返すことによって、バックエンドサービスの呼び出しをシミュレートするために使用されます。
プロパティの説明:
プロパティ名 | 型 | 説明 |
---|---|---|
type | string | 必須。値は MOCK です。 |
mockResult | string | 必須。MOCK のレスポンス結果。 |
例:
...
x-aliyun-apigateway-backend:
type: MOCK
mockResult: mock resul sample
...
1.4 x-aliyun-apigateway-Constant-parameters: 定数パラメーター
Operation Objectに適用される定数パラメーターを使用して、バックエンドサービスに適用されるパラメーターを指定します。
プロパティの説明:
プロパティ名 | 型 | 説明 |
---|---|---|
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
...
1.5 x-aliyun-apigateway-system-parameters:バックエンドサービスパラメーター
Operation Objectに適用されるバックエンドサービスパラメーターは、API バックエンドサービスのシステムパラメーターを定義するために使用されます。
プロパティの説明:
プロパティ名 | 型 | 説明 |
---|---|---|
systemName | string | 必須。システムパラメーター名。 |
backendName | string | 必須。バックエンドのパラメーター名。 |
location | String | 必須。定数パラメーターの場所。query〜header を指定することができます。 |
例:
...
x-aliyun-apigateway-system-parameters:
- systemName: CaAppId
backendName: appId
location: header
...
1.6 x-aliyun-apigateway-backend-location:バックエンドパラメーターの場所
バックエンドパラメーターの場所は、Parameter Objectに適用されます。このプロパティは、設定が x-aliyun-apigateway-paramater-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
...
1.7 x-aliyun-apigateway-backend-name: バックエンドパラメーター名
バックエンドパラメーター名は、Parameter Objectに適用されます。このプロパティは、設定が x-aliyun-apigateway-paramater-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.8 x-aliyun-apigateway-any-method: ANY メソッド
ANY メソッドは、Path Item Objectに適用されます。このメソッドは、あらゆるタイプの HTTP リクエストを受け入れるように API を設定します。
例:
...
paths:
'path/':
x-aliyun-apigateway-any-method:
...
...
2.互換性
API を定義する際、API Gateway と Swagger 仕様の違いは次のとおりです。
2.1 Swagger パラメータータイプとオリジナル API Gateway タイプの比較
Swagger タイプ | API Gateway タイプ | サポートされる検証パラメーターとルール |
---|---|---|
|
Int |
|
|
Long |
|
|
Float |
|
|
Doulbe |
|
|
String |
|
|
Boolean | - |
3.Swagger の例
このトピックでは、API Gateway に基づく Swagger 拡張機能の例を 3 つ示します。この例は、Swagger 拡張機能のほぼすべての側面を網羅しています。Swagger 拡張機能に基づく API エンティティを定義する場合、これらの例を参照できます。
注:この例は参照用です。
3.1 Swagger の例 (API Gateway バックエンドサービスが HTTP の場合)
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-paramater-handling: MAPPING
x-aliyun-apigateway-auth-type: ANONYMOUS
x-aliyun-apigateway-backend:
type: HTTP
address: 'http://www.aliyun.com'
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
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-paramater-handling: MAPPING
x-aliyun-apigateway-backend:
type: HTTP
address: 'http://www.aliyun.com'
path: '/builtin/echo/{backend}'
method: post
timeout: 10000
consumes:
- application/x-www-form-urlencoded
parameters:
- name: userId
required: true
in: path
type: string
x-aliyun-apigateway-backend-name: backend
- 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
- 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-paramater-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
3.2 Swagger の例 (API Gateway バックエンドサービスが 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-paramater-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-paramater-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-paramater-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 Swagger の例 (API Gateway バックエンドサービスが 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-paramater-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 Swagger の例 (API Gateway バックエンドサービスが 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-paramater-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