全部產品
Search

搜尋本產品

    API Gateway：匯入標準OAS定義

    文件中心

    API Gateway：匯入標準OAS定義

    更新時間：Jul 13, 2024

    API Gateway支援匯入OAS 2.0和OAS3.0格式（詳見OpenAPI Specification）的API定義，協助使用者快速將現有系統的API接入網關。API Gateway既支援標準OAS格式的API定義的匯入、也支援OAS定義擴充後的API定義匯入。

    匯入標準OAS格式的API定義

    主要包括如下過程：

    • 選擇目標分組和全域資訊。

    • 錄入OAS 2.0格式的API定義，或OAS 3.0格式的API定義

    • 進行預檢並根據檢查結果進行調整。

    • 執行匯入。

    匯入完成後，會在目標分組中建立對應的API，後續還需進行“發布到目標環境”、“介面調試”等過程，這些過程詳見API 調試。

    1. 登入API Gateway控制台。

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

    3. 在API列表頁面中，單擊右側匯入Swagger按鈕。

    4. 在彈出框中選擇匯入方式，選擇標準OAS匯入，進入配置頁面。

      1. 基本資料。主要是選擇匯入的目標分組。

        參數

        描述

        匯入的分組

        匯入的目標分組。

        重要

        如果使用OAS 2.0匯入時，目標API分組的basepath（例如建立分組）需要與OAS定義中的basepath（OAS的basePath定義）保持一致，否則將無法匯入。

        是否覆蓋

        • 當選擇覆蓋時：如果遇到請求路徑和HTTP請求衝突時，自動覆蓋（更新）原有API；

        • 當不選擇覆蓋時：如果遇到請求路徑和HTTP請求衝突時，返回錯誤提示API已經存在。

        API定義版本

        當前支援OAS 2.0和OAS 3.0的匯入方式。

      2. （可選）全域配置。設定能夠API的通用資訊。

        參數

        描述

        後端服務

        預設的後端類型都為Mock類型，可以指定API Gateway上建立的HTTP、VPC、混合、服務發現類型的後端服務（使用後端服務提高管理效率）。

        入參請求模式

        預設的方式為參數透傳，可以選擇參數透傳/參數映射。

        說明

        如果入參請求模式為透傳模式，API定義中的參數定義只會錄入path參數，query，header，formdata，body等參數將會忽略。

        API認證方式

        預設的方式為阿里雲APP，可以選擇阿里雲APP/無認證。

        說明

        • 後端服務，參數透傳，API認證為全域配置，一經配置將對所有API生效；但是如果OAS定義中使用了API Gateway支援的擴充欄位來聲明這些配置，優先順序順序為：OAS中API定義，OAS中全域定義，選填的全域配置。擴充欄位將在後文進行說明。

        • AppCode認證：安全認證模式為APP認證時，AppCode認證預設為禁止AppCode認證；簽名演算法：預設為HMAC_SHA256。

      3. API定義。確定計劃匯入的OAS定義內容，支援文本和OSS連結兩種方式：

        重要

        當前兩種方式都最多支援同時匯入100個API定義。

        1. 文本。支援填入yaml或json格式的API定義內容。通過文本填入的定義內容，最大支援256KB。

        2. OSS連結。支援填寫一個OSS檔案地址，檔案類型需為json或者yaml，且OSS地址需要允許匿名訪問。此方式下不限制檔案大小。

    5. 其他預設資訊。匯入API時需要的資訊，但並未在配置頁面中提供設定，預設值如下：

      預設資訊

      描述

      防止重放攻擊

      未開啟。

      禁止公網訪問

      未開啟。

      允許上架雲市場

      未開啟。

    6. 單擊預檢按鈕，系統將會對計劃匯入的內容進行檢查，檢測出OAS定義中的API定義和模型定義，以及警示和錯誤資訊。

      說明

      警告資訊：警告資訊可以在匯入的時候選擇忽略，但是存在警告資訊的API定義部分在匯入的過程中會被忽略；

      錯誤資訊：錯誤資訊不可忽略，錯誤資訊必須進行訂正，不訂正進行匯入會直接拋出異常。

    7. 預檢過程中沒有錯誤資訊和警告資訊（或者忽略警告資訊之後），可執行匯入。單擊匯入Swagger按鈕，系統真正開始匯入API，匯入API需要一定時間，匯入處理程序請勿關閉瀏覽器。

    8. 待系統執行完畢後，可查看到API匯入結果。

    標準OAS2.0格式與API Gateway的對應

    說明

    本章節重點介紹OAS 2.0的格式定義與API Gateway的API定義有對應的映射欄位，對於沒有對應映射的OAS中的定義，不會影響API的匯入。

    1. Swagger Object：

      1. BasePath：對應分組的BasePath，匯入時需要認證；

      2. Schemes：對應API定義中請求部分支援的協議；

    2. Path Item Object：

      1. Path：對應API定義中請求部分的請求path；

      2. Method：對應API定義中請求部分的Method，支援GET，POST，PUT，HEAD，DELETE，PATCH，OPTIONS；

    3. Operation Object：

      1. Summary：對應API定義的描述；

      2. OperationId：對應API定義的API名稱，如果存在擴充欄位“x-aliyun-apigateway-api-name”則使用擴充欄位中的內容作為API的名稱；

      3. Schemes：對應API定義中請求部分支援的協議，優先順序高於Swagger Object中的定義；

    4. Parameter Object：

      1. Name：對應API定義中請求部分的參數名稱；

      2. In：對應API定義中請求部分的參數位置，支援path，query，head，formdata；

      3. Description：對應API定義中請求部分的參數描述；

      4. Required：對應API定義中請求部分的參數是否必填；

      5. Type：對應API定義中請求部分的參數類型；

        1. query，path，head類型的參數支援string，number，integer，boolean，array；

        2. formdata類型的參數支援string，number，integer，boolean，array和file；

      6. Format：對應API定義中請求部分的參數類型，如果Format存在，Format定義優先順序高於Type類型。

        OAS參數類型與API Gateway參數類型的映射關係：

        OAS定義參數類型

        API Gateway參數定義類型

        String

        String

        Boolean

        Boolean

        Array

        Array

        Int32

        Int

        Int64

        Long

        Double

        Double

        Float

        Float

        File

        File

        說明

        1. 如果API定義的入參請求模式為透傳模式，API定義中的參數定義只會錄入path參數，query，header，formdata，body等參數將會忽略；

        2. 如果API定義的入參請求模式為透傳模式，沒有使用API Gateway擴充欄位的情況下，API定義中請求部分和後端服務部分的要求方法，請求路徑，參數定義保持一致；

        3. 對於body位置的參數，如果參數類型為參考型別，不會在API Gateway的API定義中體現，只會在產生文檔的時候體現。

    5. Response Object：

      1. HTTP Status Code：對應API定義中定義返回結果中錯誤碼定義中的錯誤碼；

      2. Description：對應API定義中定義返回結果中錯誤碼定義中的描述；

      3. Schema：對應API定義中定義返回結果中錯誤碼定義中的模型；

    6. Definitions Object：

      該項定義中的對象，在匯入的過程中，API Gateway會將模型建立在分組下，查看模型定義可以通過分組管理列表下，對應分組的操作欄中的模型管理查看。

    7. OAS 2.0格式定義舉例，如下為PetStore的介面定義，協助您快速瞭解本功能。

      swagger: "2.0"
info:
  version: "1.0.0"
  title: "Swagger Petstore 2.0"
basePath: "/"
schemes:
- "https"
- "http"
paths:
  /pet/findByStatus:
    get:
      tags:
      - "pet"
      summary: "Finds Pets by status"
      operationId: "findPetsByStatus"
      parameters:
      - name: "status"
        in: "query"
        required: true
        type: "array"
        items:
          type: "string"
          enum:
          - "available"
          - "pending"
          - "sold"
          default: "available"
        collectionFormat: "multi"
      responses:
        "200":
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/Pet"
        "400":
          description: "Invalid status value"
definitions:
  Category:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"
  Tag:
    type: "object"
    properties:
      id:
        type: "integer"
        format: "int64"
      name:
        type: "string"
  Pet:
    type: "object"
    required:
    - "name"
    - "photoUrls"
    properties:
      id:
        type: "integer"
        format: "int64"
      category:
        $ref: "#/definitions/Category"
      name:
        type: "string"
        example: "doggie"
      photoUrls:
        type: "array"
        items:
          type: "string"
      tags:
        type: "array"
        items:
          $ref: "#/definitions/Tag"
      status:
        type: "string"
        description: "pet status in the store"
        enum:
        - "available"
        - "pending"
        - "sold"

    標準OAS3.0格式與API Gateway的對應

    說明

    本章節重點介紹OAS 3.0的格式定義與API Gateway的API定義有對應的映射欄位，對於沒有對應映射的OAS中的定義，不會影響API的匯入。

    1. Path Item Object

      1. Path：對應API定義中請求部分的請求path；

      2. Method：對應API定義中請求部分的Method，支援GET，POST，PUT，HEAD，DELETE，PATCH，OPTIONS；

    2. Operation Object

      1. Summary：對應API定義的描述；

      2. OperationId：對應API定義的API名稱，如果存在擴充欄位“x-aliyun-apigateway-api-name”則使用擴充欄位中的內容作為API的名稱；

    3. Parameter Object

      1. Name：對應API定義中請求部分的參數名稱；

      2. In：對應API定義中請求部分的參數位置，支援path，query，head，formdata；

      3. Required：對應API定義中請求部分的參數是否必填；

    4. Schema Object：

      1. Description：對應API定義中請求部分的參數描述；

      2. Type：對應API定義中請求部分的參數類型；

        1. query，path，head類型的參數支援string，number，integer，boolean，array；

        2. formdata類型的參數支援string，number，integer，boolean，array和file；

      3. Format：對應API定義中請求部分的參數類型，如果Format存在，Format定義優先順序高於Type類型。

    5. Request Body Object

      1. Content：

        1. application/x-www-form-urlencoded：對應API定義中的formdata類型的參數；

        2. application/json：該項定義中的對象，在匯入的過程中，API Gateway會將模型建立在分組下，查看模型定義可以通過分組管理列表下，對應分組的操作欄中的模型管理查看。

    6. Responses Object

      1. HTTP Status Code：對應API定義中定義返回結果中錯誤碼定義中的錯誤碼；

      2. Description：對應API定義中定義返回結果中錯誤碼定義中的描述；

      3. Content：對應API定義中定義返回結果中錯誤碼定義中的模型；

    7. OAS 3.0格式定義舉例，如下為PetStore的介面定義，協助您快速瞭解本功能。

      openapi: 3.0.0
info:
  title: Swagger Petstore - OpenAPI 3.0
  version: 1.0.0
paths:
  /pet:
    put:
      tags:
        - pet
      summary: Update an existing pet
      description: Update an existing pet by Id
      operationId: updatePet
      requestBody:
        description: Update an existent pet in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Pet'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'          
        '400':
          description: Invalid ID supplied
        '404':
          description: Pet not found
        '422':
          description: Validation exception
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: Add a new pet to the store
      operationId: addPet
      requestBody:
        description: Create a new pet in the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Pet'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '400':
          description: Invalid input
        '422':
          description: Validation exception
  /pet/findByStatus:
    get:
      tags:
        - pet
      summary: Finds Pets by status
      description: Multiple status values can be provided with comma separated strings
      operationId: findPetsByStatus
      parameters:
        - name: status
          in: query
          description: Status values that need to be considered for filter
          required: false
          explode: true
          schema:
            type: string
            default: available
            enum:
              - available
              - pending
              - sold
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'          
            application/xml:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
        '400':
          description: Invalid status value
components:
  schemas:
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: Dogs
      xml:
        name: category
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
      xml:
        name: tag
    Pet:
      required:
        - name
        - photoUrls
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: doggie
        category:
          $ref: '#/components/schemas/Category'
        photoUrls:
          type: array
          xml:
            wrapped: true
          items:
            type: string
            xml:
              name: photoUrl
        tags:
          type: array
          xml:
            wrapped: true
          items:
            $ref: '#/components/schemas/Tag'
        status:
          type: string
          description: pet status in the store
          enum:
            - available
            - pending
            - sold
      xml:
        name: pet

    匯入具有API Gateway擴充欄位的OAS格式定義

    詳見匯出標準OAS定義。