API Gateway：匯出標準OAS定義

概述

本文主要介紹了API Gateway可以將API資源匯出為標準OAS定義，結合API Gateway的匯入標準OAS定義，您可以：

1. 跨平台跨地區遷移資料：藉助API Gateway的匯出和匯入功能，您可以方便地從其他平台或API Gateway匯出OAS規範的API資料，並在其他地區或帳號下實現API的快速匯入，簡化您遷移的過程。

2. API發布與擴充：通過將使用標準OAS規範的API定義轉化為API Gateway的API資源，您能夠快速在API Gateway建立和配置API，然後根據您的需求，自訂和擴充API的功能和行為。通過API Gateway的靈活性，您可以更好地管理和控制API的存取權限、流量限制和請求轉寄，提供高度可靠和安全的API服務。

3. 整合與協作：通過將API匯出為標準OAS規範的API定義，您可以方便地與其他開發工具或平台進行整合。這樣，您可以與團隊成員或第三方開發人員更好地協作，共用API資源的詳細資料，減少溝通成本和開發時間。

匯出標準OAS格式的API定義

匯出API定義支援以分組為單位進行API匯出，也支援通過批量勾選API進行匯出。

操作步驟

1. 通過分組匯出API定義

   1. 登入API Gateway控制台。

   2. 在控制台左側菜單中，選擇API 管理>分組管理。

   3. 在分組列表頁面中，選擇對應的API分組。操作列下的>匯出API定義。

   4. 在彈出框匯出API定義中指定匯出的資料格式，環境以及是否需要匯出API Gateway拓展定義。

2. 直接匯出API定義

   1. 登入API Gateway控制台。

   2. 在控制台左側菜單中，選擇API 管理>API列表。

   3. 在API 列表頁面中，勾選要匯出的API名稱，然後單擊更多操作 > 匯出API定義。

   4. 在彈出框匯出API定義中指定匯出的資料格式，環境以及是否需要匯出API Gateway拓展定義。

API Gateway擴充定義說明

如果在匯出OAS規範的定義中選擇了匯出API Gateway擴充欄位，在匯出的API定義檔案中會添加網關的擴充欄位。

說明

1. 以分組為單位匯出時，會匯出分組的base path；

2. 每次可以匯出的API數量限制為300個API，若超出限制預設匯出分組下前300個API；

3. 分組模型管理裡中定義的模型定義如果無法解析，匯出的內容中將不包含模型定義；

4. 以API為單位匯出時，所有勾選的API會匯出到一個檔案中；

5. 以API為單位匯出時，如果存在API有相同的path和method，只會匯出其中一個；

6. 未勾選匯出API Gateway擴充欄位時，匯出OAS檔案中的OperationId為API定義的請求path和請求method的拼接後的字串，如“export1ByGET”；

7. 勾選匯出API Gateway擴充欄位後，在API Gateway定義API以外的內容，如綁定的外掛程式、授權的APP、分組的網域名稱、後端服務在各環境上的定義等，均不會被匯出。

樣本

如下為使用API Gateway提供的分組匯出帶有擴充定義的OAS2.0內容：

swagger: '2.0'
info:
  description: Export from api group xxx
  version: 1.0.0
  title: Api Gateway API
basePath: /export
paths:
  /export1/{pathParam}:
    get:
      summary: 測試匯出1
      operationId: export1pathParamByGET
      schemes:
        - http
        - https
      parameters:
        - name: pathParam
          in: path
          description: 測試path參數
          required: true
          type: string
          maxLength: 10
          x-aliyun-apigateway-parameter-demo: pathValue
          x-aliyun-apigateway-backend-name: pathParam
          x-aliyun-apigateway-backend-location: path
        - name: headParam
          in: header
          description: 測試head參數
          required: false
          type: string
          x-aliyun-apigateway-parameter-demo: headerValue
          x-aliyun-apigateway-backend-name: headParam
          x-aliyun-apigateway-backend-location: query
        - name: queryParam
          in: query
          description: 測試query參數
          required: false
          type: string
          x-aliyun-apigateway-parameter-demo: queryValue
          x-aliyun-apigateway-backend-name: queryParam
          x-aliyun-apigateway-backend-location: header
      responses:
        '200':
          description: 成功
          x-aliyun-apigateway-response-messages: success
        '400':
          description: 用戶端錯誤
          x-aliyun-apigateway-response-messages: clent error
        '500':
          description: 服務端錯誤
          x-aliyun-apigateway-response-messages: server error
      x-aliyun-apigateway-system-parameters:
        - backendName: testClientIp
          systemName: CaClientIp
          location: header
      x-aliyun-apigateway-constant-parameters:
        - backendName: constantparam
          location: header
          value: constantValue
          descriptoin: 測試常量參數
      x-aliyun-apigateway-api-name: export_1
      x-aliyun-apigateway-api-market-enable: false
      x-aliyun-apigateway-api-force-nonce-check: true
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-auth-type: APP
      x-aliyun-apigateway-api-enable-internet: true
      x-aliyun-apigateway-failed-demo: '{"result":"fail"}'
      x-aliyun-apigateway-success-demo: '{"result":"success"}'
      x-aliyun-apigateway-app-code-type: DEFAULT
      x-aliyun-apigateway-backend:
        body: good job
        statusCode: 200
        header:
          - name: test
            value: header1
        type: MOCK
  /export2/*:
    x-aliyun-apigateway-any-method:
      operationId: export_2
      description: 測試匯出1
      x-aliyun-apigateway-api-market-enable: false
      x-aliyun-apigateway-api-force-nonce-check: false
      x-aliyun-apigateway-api-enable-internet: true
      x-aliyun-apigateway-parameter-handling: PASSTHROUGH
      x-aliyun-apigateway-auth-type: ANONYMOUS
      x-aliyun-apigateway-success-demo: '{"result":"success"}'
      x-aliyun-apigateway-failed-demo: '{"result":"fail"}'
      schemes:
        - http
        - https
      x-aliyun-apigateway-backend:
        body: good job
        statusCode: 200
        header:
          - name: test
            value: header1
        type: MOCK
      x-aliyun-apigateway-constant-parameters:
        - backendName: constantparam
          location: header
          value: constantValue
          descriptoin: 測試常量參數
      x-aliyun-apigateway-system-parameters:
        - backendName: testClientIp
          systemName: CaClientIp
          location: header
      responses:
        '200':
          description: 成功
          briefMessage: success
          schema:
            $ref: testModel
        '400':
          description: 用戶端錯誤
          briefMessage: clent error
          schema:
            $ref: testModel
        '500':
          description: 服務端錯誤
          briefMessage: server error
definitions:
  testModel:
    type: object
    required:
      - name
    properties:
      dogProject:
        type: object
        properties:
          name:
            type: string
            maxLength: 10
          id:
            type: integer
            format: int64
      name:
        type: string
        pattern: ^\d{3}-\d{2}-\d{4}$
      id:
        type: integer
        format: int64
      status:
        type: string