すべてのプロダクト
Search
ドキュメントセンター

:Swagger のインポートによる AP

最終更新日:Mar 20, 2020

Swagger は、API 定義を記述するための仕様で、バックエンドサービス用の API の定義と記述に広く使用されています。Swagger 2.0 ファイルを API Gateway にインポートすると、API を作成できます。詳細は、「ImportSwagger による API の作成」をご参照ください。または、次の図のようにコンソールで操作してください。

import swagger

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:匿名

  1. ...
  2. paths:
  3. 'path/':
  4. get:
  5. x-aliyun-apigateway-auth-type: ANONYMOUS
  6. ...

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:リクエストパラメータマッピング。

  1. ...
  2. paths:
  3. 'path/':
  4. get:
  5. x-aliyun-apigateway-paramater-handling: MAPPING
  6. ...

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 です。

  1. ...
  2. x-aliyun-apigateway-backend:
  3. type: HTTP
  4. address: http://10.10.100.2:8000
  5. path: "/users/{userId}"
  6. method: GET
  7. timeout: 7,000
  8. ...

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 です。

  1. ...
  2. x-aliyun-apigateway-backend:
  3. type: HTTP_VPC
  4. vpcAccessName: vpcAccess1
  5. path: "/users/{userId}"
  6. method: GET
  7. timeout: 10,000
  8. ...

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

FC バックエンドタイプは、Function Compute サービスにアクセスするためのサービスアドレスを設定するために使用されます。

プロパティの説明

プロパティ名 説明
type string 必須。値は FC です。
fcRegion string 必須。FC のリージョン。
serviceName string 必須。FC のサービス名。
functionName string 必須。FC の関数名
arn string 必須。FC の Arn。

  1. ...
  2. x-aliyun-apigateway-backend:
  3. type: FC
  4. fcRegion: cn-shanghai
  5. serviceName: fcService
  6. functionName: fcFunction
  7. arn: acs:ram::111111111:role/aliyunapigatewayaccessingfcrole
  8. ...

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

MOCK バックエンドタイプは、 デフォルトのレスポンスを返すことによって、バックエンドサービスの呼び出しをシミュレートするために使用されます。

プロパティの説明

プロパティ名 説明
type string 必須。値は MOCK です。
mockResult string 必須。MOCK のレスポンス結果。

  1. ...
  2. x-aliyun-apigateway-backend:
  3. type: MOCK
  4. mockResult: mock resul sample
  5. ...

1.4 x-aliyun-apigateway-Constant-parameters: 定数パラメーター

Operation Objectに適用される定数パラメーターを使用して、バックエンドサービスに適用されるパラメーターを指定します。

プロパティの説明

プロパティ名 説明
backendName string 必須。バックエンドのパラメーター名。
value string 必須。定数値。
location String 必須。定数パラメーターの場所。query〜header を指定することができます。
description string オプション。定数パラメーターの説明。

  1. ...
  2. x-aliyun-apigateway-constant-parameters:
  3. - backendName: swaggerConstant
  4. value: swaggerConstant
  5. location: header
  6. description: description of swagger
  7. ...

1.5 x-aliyun-apigateway-system-parameters:バックエンドサービスパラメーター

Operation Objectに適用されるバックエンドサービスパラメーターは、API バックエンドサービスのシステムパラメーターを定義するために使用されます。

プロパティの説明

プロパティ名 説明
systemName string 必須。システムパラメーター名。
backendName string 必須。バックエンドのパラメーター名。
location String 必須。定数パラメーターの場所。query〜header を指定することができます。

  1. ...
  2. x-aliyun-apigateway-system-parameters:
  3. - systemName: CaAppId
  4. backendName: appId
  5. location: header
  6. ...

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

バックエンドパラメーターの場所は、Parameter Objectに適用されます。このプロパティは、設定が x-aliyun-apigateway-paramater-handling: MAPPING の場合にのみ適用されます。パラメーターマッピングの設定後、バックエンドサービスがリクエストを送信するときに、このプロパティは、パラメーターの場所を指定するために使用されます 。

値の範囲

  • path
  • header
  • query
  • formData

  1. ...
  2. parameters:
  3. - name: swaggerHeader
  4. in: header
  5. required: false
  6. type: number
  7. format: double
  8. minimum: 0.1
  9. maximum: 0.5
  10. x-aliyun-apigateway-backend-location: query
  11. x-aliyun-apigateway-backend-name: backendQuery
  12. ...

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

バックエンドパラメーター名は、Parameter Objectに適用されます。このプロパティは、設定が x-aliyun-apigateway-paramater-handling: MAPPING の場合にのみ適用されます。パラメーターマッピングの設定後、バックエンドサービスがリクエストを送信するときに、このプロパティは、パラメーター名を指定するために使用されます 。

  1. ...
  2. parameters:
  3. - name: swaggerHeader
  4. in: header
  5. required: false
  6. type: number
  7. format: double
  8. minimum: 0.1
  9. maximum: 0.5
  10. x-aliyun-apigateway-backend-location: query
  11. x-aliyun-apigateway-backend-name: backendQuery
  12. ...

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

ANY メソッドは、Path Item Objectに適用されます。このメソッドは、あらゆるタイプの HTTP リクエストを受け入れるように API を設定します。

  1. ...
  2. paths:
  3. 'path/':
  4. x-aliyun-apigateway-any-method:
  5. ...
  6. ...

2.互換性

API を定義する際、API Gateway と Swagger 仕様の違いは次のとおりです。

2.1 Swagger パラメータータイプとオリジナル API Gateway タイプの比較

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

3.Swagger の例

このトピックでは、API Gateway に基づく Swagger 拡張機能の例を 3 つ示します。この例は、Swagger 拡張機能のほぼすべての側面を網羅しています。Swagger 拡張機能に基づく API エンティティを定義する場合、これらの例を参照できます。

注:この例は参照用です。

3.1 Swagger の例 (API Gateway バックエンドサービスが HTTP の場合)

  1. swagger: '2.0'
  2. basePath: /
  3. info:
  4. version: '0.9'
  5. title: Aliyun Api Gateway Swagger Sample
  6. schemes:
  7. - http
  8. - https
  9. paths:
  10. '/http/get/mapping/{userId}':
  11. get:
  12. operationId: case1
  13. schemes:
  14. - http
  15. - https
  16. x-aliyun-apigateway-paramater-handling: MAPPING
  17. x-aliyun-apigateway-auth-type: ANONYMOUS
  18. x-aliyun-apigateway-backend:
  19. type: HTTP
  20. address: 'http://www.aliyun.com'
  21. path: '/builtin/echo/{userId}'
  22. method: get
  23. timeout: 10000
  24. parameters:
  25. - name: userId
  26. in: path
  27. required: true
  28. type: string
  29. - name: swaggerQuery
  30. in: query
  31. required: false
  32. default: '123465'
  33. type: integer
  34. format: int32
  35. minimum: 0
  36. maximum: 100
  37. - name: swaggerHeader
  38. in: header
  39. required: false
  40. type: number
  41. format: double
  42. minimum: 0.1
  43. maximum: 0.5
  44. x-aliyun-apigateway-backend-location: query
  45. x-aliyun-apigateway-backend-name: backendQuery
  46. x-aliyun-apigateway-constant-parameters:
  47. - backendName: swaggerConstant
  48. value: swaggerConstant
  49. location: header
  50. description: description of swagger
  51. x-aliyun-apigateway-system-parameters:
  52. - systemName: CaAppId
  53. backendName: appId
  54. location: header
  55. responses:
  56. '200':
  57. description: 200 description
  58. '400':
  59. description: 400 description
  60. '/echo/test/post/{userId}':
  61. post:
  62. operationId: testpost
  63. schemes:
  64. - http
  65. - https
  66. x-aliyun-apigateway-paramater-handling: MAPPING
  67. x-aliyun-apigateway-backend:
  68. type: HTTP
  69. address: 'http://www.aliyun.com'
  70. path: '/builtin/echo/{backend}'
  71. method: post
  72. timeout: 10000
  73. consumes:
  74. - application/x-www-form-urlencoded
  75. parameters:
  76. - name: userId
  77. required: true
  78. in: path
  79. type: string
  80. x-aliyun-apigateway-backend-name: backend
  81. - name: swaggerQuery1
  82. in: query
  83. required: false
  84. default: '123465'
  85. type: integer
  86. format: int32
  87. minimum: 0
  88. maximum: 100
  89. x-aliyun-apigateway-enum: 1,2,3
  90. - name: swaggerQuery2
  91. in: query
  92. required: false
  93. type: string
  94. x-aliyun-apigateway-backend-location: header
  95. x-aliyun-apigateway-backend-name: backendHeader
  96. - name: swaggerHeader
  97. in: header
  98. required: false
  99. type: number
  100. format: double
  101. minimum: 0.1
  102. maximum: 0.5
  103. x-aliyun-apigateway-backend-location: query
  104. x-aliyun-apigateway-backend-name: backendQuery
  105. - name: swaggerFormdata
  106. in: formData
  107. required: true
  108. type: string
  109. responses:
  110. '200':
  111. description: 200 description
  112. '400':
  113. description: 400 description
  114. x-aliyun-apigateway-any-method:
  115. operationId: case2
  116. schemes:
  117. - http
  118. - https
  119. x-aliyun-apigateway-paramater-handling: MAPPING
  120. x-aliyun-apigateway-backend:
  121. type: HTTP
  122. address: 'http://www.aliyun.com'
  123. path: '/builtin/echo/{abc}'
  124. method: post
  125. timeout: 10000
  126. parameters:
  127. - name: userId
  128. in: path
  129. required: false
  130. default: '123465'
  131. type: integer
  132. format: int32
  133. minimum: 0
  134. maximum: 100
  135. x-aliyun-apigateway-backend-name: abc
  136. x-aliyun-apigateway-backend-location: path
  137. responses:
  138. '200':
  139. description: 200 description
  140. '400':
  141. description: 400 description

3.2 Swagger の例 (API Gateway バックエンドサービスが HTTP-VPC の場合)

  1. swagger: '2.0'
  2. basePath: /
  3. info:
  4. version: '0.9'
  5. title: Aliyun Api Gateway Swagger Sample
  6. schemes:
  7. - http
  8. - https
  9. paths:
  10. '/http/get/mapping/{userId}':
  11. get:
  12. operationId: case1
  13. schemes:
  14. - http
  15. - https
  16. x-aliyun-apigateway-paramater-handling: MAPPING
  17. x-aliyun-apigateway-backend:
  18. type: HTTP-VPC
  19. vpcAccessName: vpcName1
  20. path: '/builtin/echo/{userId}'
  21. method: get
  22. timeout: 10000
  23. parameters:
  24. - name: userId
  25. in: path
  26. required: true
  27. type: string
  28. - name: swaggerQuery
  29. in: query
  30. required: false
  31. default: '123465'
  32. type: integer
  33. format: int32
  34. minimum: 0
  35. maximum: 100
  36. - name: swaggerHeader
  37. in: header
  38. required: false
  39. type: number
  40. format: double
  41. minimum: 0.1
  42. maximum: 0.5
  43. x-aliyun-apigateway-backend-location: query
  44. x-aliyun-apigateway-backend-name: backendQuery
  45. responses:
  46. '200':
  47. description: 200 description
  48. '400':
  49. description: 400 description
  50. '/echo/test/post':
  51. post:
  52. operationId: testpost
  53. schemes:
  54. - http
  55. - https
  56. x-aliyun-apigateway-paramater-handling: MAPPING
  57. x-aliyun-apigateway-backend:
  58. type: HTTP-VPC
  59. vpcAccessName: vpcName2
  60. path: '/builtin/echo'
  61. method: post
  62. timeout: 10000
  63. consumes:
  64. - application/x-www-form-urlencoded
  65. parameters:
  66. - name: swaggerQuery1
  67. in: query
  68. required: false
  69. default: '123465'
  70. type: integer
  71. format: int32
  72. minimum: 0
  73. maximum: 100
  74. - name: swaggerQuery2
  75. in: query
  76. required: false
  77. type: string
  78. x-aliyun-apigateway-backend-location: header
  79. x-aliyun-apigateway-backend-name: backendHeader
  80. - name: swaggerHeader
  81. in: header
  82. required: false
  83. type: number
  84. format: double
  85. minimum: 0.1
  86. maximum: 0.5
  87. x-aliyun-apigateway-backend-location: query
  88. x-aliyun-apigateway-backend-name: backendQuery
  89. - name: swaggerFormdata
  90. in: formData
  91. required: true
  92. type: string
  93. responses:
  94. '200':
  95. description: 200 description
  96. '400':
  97. description: 400 description
  98. x-aliyun-apigateway-any-method:
  99. operationId: case2
  100. schemes:
  101. - http
  102. - https
  103. x-aliyun-apigateway-paramater-handling: PASSTHROUGH
  104. x-aliyun-apigateway-backend:
  105. type: HTTP-VPC
  106. vpcAccessName: vpcName3
  107. path: '/builtin/echo'
  108. method: post
  109. timeout: 10000
  110. responses:
  111. '200':
  112. description: 200 description
  113. '400':
  114. description: 400 description

3.3 Swagger の例 (API Gateway バックエンドサービスが Function Compute の場合)

  1. swagger: '2.0'
  2. basePath: /
  3. info:
  4. version: '0.9'
  5. title: Aliyun Api Gateway Swagger Sample
  6. schemes:
  7. - http
  8. - https
  9. paths:
  10. '/http/get/mapping/{userId}':
  11. get:
  12. operationId: case1
  13. schemes:
  14. - http
  15. - https
  16. x-aliyun-apigateway-paramater-handling: MAPPING
  17. x-aliyun-apigateway-backend:
  18. type: FC
  19. fcRegion: cn-shanghai
  20. serviceName: fcService
  21. functionName: fcFunction
  22. arn: acs:ram::111111111:role/aliyunapigatewayaccessingfcrole
  23. parameters:
  24. - name: userId
  25. in: path
  26. required: true
  27. type: string
  28. responses:
  29. '200':
  30. description: 200 description
  31. '400':
  32. description: 400 description

3.4 Swagger の例 (API Gateway バックエンドサービスが MOCK の場合)

  1. swagger: '2.0'
  2. basePath: /
  3. info:
  4. version: '0.9'
  5. title: Aliyun Api Gateway Swagger Sample
  6. schemes:
  7. - http
  8. paths:
  9. '/mock/get/mapping/{userId}':
  10. get:
  11. operationId: case1
  12. schemes:
  13. - http
  14. - https
  15. x-aliyun-apigateway-paramater-handling: MAPPING
  16. x-aliyun-apigateway-backend:
  17. type: MOCK
  18. mockResult: mock resul sample
  19. mockStatusCode: 200
  20. mockHeaders:
  21. - name: server
  22. value: mock
  23. - name: proxy
  24. value: GW
  25. parameters:
  26. - name: userId
  27. in: path
  28. required: true
  29. type: string
  30. responses:
  31. '200':
  32. description: 200 description
  33. '400':
  34. description: 400 description