匯入API Gateway的擴充Swagger定義 - API Gateway

Swagger是一種用於描述API定義的規範，被廣泛應用於定義和描述後端應用服務的API。現在，API Gateway支援匯入Swagger 2.0的檔案來建立API，您可以參考ImportSwagger，或在控制台上進行操作，入口見下圖：

API Gateway的Swagger擴充基於Swagger 2.0，可以建立API實體的Swagger定義，並將Swagger匯入API Gateway用於大量建立或者更新API實體。API Gateway的預配置是swagger2.0，它可支援併兼容大部分的Swagger規範，但存在一定的差異性。

本章節主要對基於Swagger的API Gateway擴充進行介紹，並提供相應的樣本來闡述用法。

說明

Swagger中所有參數與取值均大小寫敏感

一、Swagger擴充

Swagger擴充主要是對於swagger原生Operation Object進行擴充，增加認證、參數映射以及後端服務等擴充。除此之外，增加處理any方法的擴充，用於捕獲任意HTTP要求方法。所有擴充均以x-aliyun-apigateway-開頭，具體擴充內容如下：

1.1 x-aliyun-apigateway-auth-type: 授與類型

授與類型，應用於Operation Object。用於指定該API的授與類型，其中：

取值範圍：

APP（預設值）: 阿里雲API GatewayAPP授權
ANONYMOUS: 匿名

樣本：

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

1.2 x-aliyun-apigateway-api-market-enable: 雲市場支援

授與類型，應用於Operation Object。用於指定該API是否可以上架雲市場，其中：

取值範圍：

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是否進行NONCE強制校正，其中：

取值範圍：

true
false（預設）

樣本：

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

1.4 x-aliyun-apigateway-parameter-handling: API映射關係

API映射關係，應用於Operation Object，用於指定請求參數與後端服務參數的映射關係。當映射關係選擇PASSTHROUGH時，Parameter Object不支援 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

HTTP的後端類型用於直接配置後端服務地址，一般用於後端地址可以直接存取的場合。

屬性說明：

屬性名稱	類型	描述
type	string	必填；值為HTTP
address	string	必填；用於標識後端服務地址
path	string	選填：用於標識後端服務路徑。支援路徑變數。預設與跟path值相同
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
...

1.5.2 後端服務類型：HTTP-VPC

HTTP-VPC的後端類型用於後端服務在VPC網路內的場合，需要先建立VPC授權，具體操作請參考建立後端服務為VPC內資源的API，使用VPC授權名匯入。

屬性說明：

屬性名稱	類型	描述
type	string	必填；值為：HTTP-VPC
vpcAccessName	string	必填；後端服務使用的VPC執行個體名稱
path	string	選填：用於標識後端服務路徑。支援路徑變數。預設與根path相等
method	string	必填：後端要求方法
timeout	int	選填，預設為10000。該屬性取值範圍為[500,30000]

樣本：

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

1.5.3 後端服務類型：FC

API Gateway後端服務類型為FUNCTION COMPUTE。

屬性說明：

屬性名稱	類型	描述
type	string	必填；值為：FC
fcRegion	string	必填；Function Compute所在地區
serviceName	string	必填：Function Compute服務名
functionName	string	必填：Function Compute函數名
arn	string	選填，Function ComputeRAM授權

樣本：

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

1.5.4 後端服務類型： MOCK

MOCK的後端類型，用來類比最初預定的返回結果。

屬性說明：

屬性名稱	類型	描述
type	string	必填；值為：MOCK
mockResult	string	必填；mock返回結果
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
...

1.6 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.7 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.8 x-aliyun-apigateway-backend-location: 後端參數位置

後端參數位置，應用於 Parameter Object。該屬性僅在 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
      ...

1.9 x-aliyun-apigateway-backend-name: 後端參數名稱

後端參數名稱，應用於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: query對Model支援

後端參數名稱，應用於Parameter Object。用於對Query進行模型定義。當parameter為String類型，同時定義為query參數時，可以使用。

樣本：

      ...
      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方法

ANY方法，應用於Path Item Object，用於設定API可以接受任意類型的HTTP請求。

樣本：

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

1.12 x-aliyun-apigateway-app-code-type: Appcode簡單認證

Appcode簡單認證，應用於Operation Object。用於指定該API是否支援APPcode簡單認證，其中：

取值範圍：

DEFAULT（預設值）
DISABLE: 禁用
HEADER: 通過HEADER傳入appcode
HEADER_QUERY: 可以通過HEADER或Query傳入appcode

樣本：

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

二、相容性說明

API Gateway與Swagger規範在定義API時存在一定差異性，包括：

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	Double	mininum maxnum
type:string	String	maxLength enumValues pattern
type:boolean format:Boolean	Boolean	-

2.2 consumes欄位支援

當Swagger設定檔存在formdata型別參數時，需要配置consumes節點。API Gateway現在只支援application/x-www-form-urlencoded類型。

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

三、Swagger樣本

本章節提供三個基於API Gateway的swagger擴充樣本。樣本幾乎涵蓋了所有的擴充內容，為基於swagger擴充自訂API實體提供便利。

說明

樣本僅供參考。

3.1 API Gateway後端服務為HTTP的Swagger樣本

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: 非同步任務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: int32
        description: 成功數量
      totalSize:
        type: number
        format: float
        description: 請求總數
  ResultOfGeneratePicturesVO:
    type: object
    properties:
      model:
        description: 返回內容
        $ref: '#/definitions/GeneratePicturesVO'
        title: GeneratePicturesVO
      requestId:
        type: string
        description: 請求ID

3.2 API Gateway後端服務為HTTP-VPC的Swagger樣本

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 API Gateway後端服務為FunctionCompute的Swagger樣本

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 API Gateway後端服務為MOCK的Swagger樣本

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

四、特別說明

以下內容請密切關注，直接影響swagger的匯入功能使用

4.1 全域域的支援

以下標籤支援全域範圍的定義。當該標籤原本範圍不存在該定義時，會自動填滿全域域的定義值；若存在，則優先使用原本範圍的定義值。

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 Definition說明

swagger匯入現在支援模型定義，但是與原有swagger規範存在差異 模型的定義主要用於SDK的產生，所以會在原有swagger規範的基礎上增加了一些限制條件：

swagger中schema標籤僅支援：$ref類型
swagger中Definition的model僅支援object type類型的模型定義
swagger中Definition的model中存在array定義，其引用$ref應與title標籤配合使用。array類型預設在SDK產生時對應產生ArrayList