操作場景

Swagger是基于OpenAPI規范構建的開源工具，可以幫助您設計、構建、記錄以及使用Rest API。API網關支持導入Swagger 2.0定義的API到已有的API分組或新的API分組。

導入API支持單個API導入和批量API導入，主要取決于Swagger文件中包含的API數量。

將Swagger或OpenAPI定義的API導入到API網關，支持導入到新分組和導入到已有分組兩種方式。導入前您需要在API定義中補全API網關的擴展定義。

導入到新分組注意事項

將API定義導入到一個新的分組，導入過程中系統會自動創建一個新的API分組，并將導入的API歸屬到該分組。

適用于將一份全新且完整的API導入到API網關。

導入API前，請注意以下事項：

• API網關中API分組和API的配額滿足需求。
• 使用Swagger info或OpenAPI info的title作為API分組名稱，新創建的API分組名稱不能與已有的API分組名稱重名。
• 導入的API定義中，如果存在沖突，那么根據系統導入的先后順序，先導入的API會顯示導入成功，后導入的API會顯示導入失敗。例如導入的API定義中存在2個名稱相同或請求路徑相同的API，那么先導入的API會顯示導入成功，后導入的會顯示導入失敗。
• 如果選擇擴展覆蓋，當導入API的擴展定義項名稱與已有策略（ACL，流量控制等）名稱相同時，則會覆蓋已有策略（ACL，流量控制等）。
  導入的API不會自動發布到環境，導入時可以選擇“立即發布”或者“稍后發布”，您可以自行選擇策略。

導入到已有分組注意事項

將API定義導入到一個已有的分組，導入過程中不會刪除分組中已有的API，只是將新增的API導入分組。

適用于將一個新的API或者一個修改后的API導入到已有的分組。

導入API前，請注意以下事項：

• API網關中API的配額滿足需求。
• 導入的API定義與已有的API定義沖突時，您可以選擇使用導入的API定義覆蓋已有的API定義，或者保留已有的API定義，此時導入的API定義會顯示導入失敗。
• 如果選擇擴展覆蓋，當導入API的擴展定義項名稱與已有策略（ACL，流量控制等）名稱相同時，則會覆蓋已有策略（ACL，流量控制等）。
• 導入的API不會自動發布到環境，導入時可以選擇“立即發布”或者“稍后發布”，您可以自行選擇策略。

操作步驟

步驟 1 進入API網關控制臺頁面。

步驟 2 根據實際業務在左側導航欄上方選擇實例。

步驟 3 在左側導航欄選擇“API管理 > API列表”。

步驟 4 單擊導入API。

您也可以參考以下示例導入API到API網關：

• 導入HTTP類型后端服務API示例
• 導入HTTP VPC類型后端服務API示例
• 導入MOCK類型后端服務API示例

導入HTTP類型后端服務API示例

包含IAM認證和請求參數編排的GET方法API定義，后端服務類型為HTTP。

Swagger示例：

swagger: "2.0" 
info: 
  title: "importHttpEndpoint10" 
  description: "import apis" 
  version: "1.0" 
host: "api.account.com" 
paths: 
  '/http/{userId}': 
    get: 
      operationId: "getUser3" 
      description: "get user by userId" 
      security: 
      - apig-auth-iam: [] 
      schemes: 
      - https 
      parameters: 
      - name: "test" 
        description: "authorization token" 
        type: "string" 
        in: "header" 
        required: true 
      - name: "userId" 
        description: "user id" 
        type: "string" 
        in: "path" 
        required: true 
      responses: 
        "200": 
          description: "user information" 
      x-apigateway-request-type: "public" 
      x-apigateway-cors: true 
   
      x-apigateway-match-mode: "NORMAL" 
      x-apigateway-backend: 
        type: "HTTP" 
        parameters: 
        - name: "userId" 
          value: "userId" 
          in: "query" 
          origin: "REQUEST" 
          description: "user id" 
        - name: "X-Invoke-User" 
          value: "apigateway" 
          in: "header" 
          origin: "CONSTANT" 
          description: "invoke user" 
        httpEndpoints: 
          address: "example.com" 
          scheme: "http" 
          method: "GET" 
          path: "/users" 
          timeout: 30000 
securityDefinitions: 
  apig-auth-app: 
    in: header 
    name: Authorization 
    type: apiKey 
    x-apigateway-auth-type: AppSigv1 
  apig-auth-iam: 
    in: header 
    name: unused 
    type: apiKey 
    x-apigateway-auth-type: IAM

OpenAPI示例：

openapi: 3.0.0 
info: 
  title: importHttpEndpoint10 
  version: '1.0' 
servers: 
  - url: >- 
      //abc.com 
  - url: >- 
      //abc.com 
paths: 
  '/http/{userId}': 
    get: 
      description: get user by userId 
      operationId: getUser3 
      parameters: 
        - description: authorization token 
          example: '' 
          in: header 
          name: test 
          required: true 
          schema: 
            maxLength: 0 
            maximum: 0 
            minimum: 0 
            type: string 
          x-apigateway-pass-through: always 
        - description: user id 
          example: '' 
          in: path 
          name: userId 
          required: true 
          schema: 
            maxLength: 0 
            maximum: 0 
            minimum: 0 
            type: string 
          x-apigateway-pass-through: always 
      responses: 
        default-cors: 
          description: response example 
          x-apigateway-result-failure-sample: '' 
          x-apigateway-result-normal-sample: '' 
      security: 
        - apig-auth-iam: [] 
      servers: 
        - url: >- 
            //abc.com 
      x-apigateway-backend: 
        httpEndpoints: 
          address: example.com 
          description: '' 
          enableClientSsl: false 
          method: GET 
          path: /users 
          retryCount: '-1' 
          scheme: http 
          timeout: 30000 
        parameters: 
          - description: invoke user 
            in: HEADER 
            name: X-Invoke-User 
            origin: CONSTANT 
            value: apigateway 
          - description: user id 
            in: QUERY 
            name: userId 
            origin: REQUEST 
            value: userId 
        type: HTTP 
      x-apigateway-cors: true 
   
      x-apigateway-match-mode: NORMAL 
      x-apigateway-request-type: public 
      x-apigateway-response: default 
components: 
  responses: 
    default-cors: 
      description: response example 
      headers: 
        Access-Control-Allow-Origin: 
          schema: 
            default: '*' 
            type: string 
  securitySchemes: 
    apig-auth-app: 
      in: header 
      name: Authorization 
      type: apiKey 
      x-apigateway-auth-type: AppSigv1 
    apig-auth-app-header: 
      in: header 
      name: Authorization 
      type: apiKey 
      x-apigateway-auth-opt: 
        appcode-auth-type: header 
      x-apigateway-auth-type: AppSigv1 
    apig-auth-iam: 
      in: header 
      name: unused 
      type: apiKey 
      x-apigateway-auth-type: IAM 
  x-apigateway-responses: 
    default: {}

導入HTTP VPC類型后端服務API示例

包含APP認證和請求參數編排的ANY方法API定義，后端服務使用VPC通道。

Swagger示例：

swagger: "2.0" 
info: 
  title: "importHttpVpcEndpoint" 
  description: "import apis" 
  version: "1.0" 
host: "api.account.com" 
paths: 
  '/http-vpc': 
    x-apigateway-any-method: 
      operationId: "userOperation" 
      description: "user operation resource" 
      security: 
      - apig-auth-app: [] 
      schemes: 
      - https 
      parameters: 
      - name: "Authorization" 
        description: "authorization signature" 
        type: "string" 
        in: "header" 
        required: true 
      responses: 
        "default": 
          description: "endpoint response" 
      x-apigateway-request-type: "public" 
      x-apigateway-cors: true 
   
      x-apigateway-match-mode: "SWA" 
      x-apigateway-backend: 
        type: "HTTP-VPC" 
        parameters: 
        - name: "X-Invoke-User" 
          value: "apigateway" 
          in: "header" 
          origin: "CONSTANT" 
          description: "invoke user" 
        httpVpcEndpoints: 
          name: "userVpc" 
          scheme: "http" 
          method: "GET" 
          path: "/users" 
          timeout: 30000 
securityDefinitions: 
  apig-auth-app: 
    in: header 
    name: Authorization 
    type: apiKey 
    x-apigateway-auth-type: AppSigv1 
  apig-auth-iam: 
    in: header 
    name: unused 
    type: apiKey 
    x-apigateway-auth-type: IAM

OpenAPI示例：

openapi: 3.0.0 
info: 
  description: import apis 
  title: importHttpVpcEndpoint 
  version: '1.0' 
servers: 
  - url: >- 
      //abc.com 
  - url: >- 
      //abc.com 
paths: 
  /http-vpc: 
    x-apigateway-any-method: 
      description: user operation resource 
      operationId: userOperation 
      parameters: 
        - description: authorization signature 
          example: '' 
          in: header 
          name: Authorization 
          required: true 
          schema: 
            maxLength: 0 
            maximum: 0 
            minimum: 0 
            type: string 
          x-apigateway-pass-through: always 
      responses: 
        default-cors: 
          description: response example 
          x-apigateway-result-failure-sample: '' 
          x-apigateway-result-normal-sample: '' 
      security: 
        - apig-auth-app: [] 
      servers: 
        - url: >- 
            //abc.com 
      x-apigateway-backend: 
        httpVpcEndpoints: 
          cascade_flag: false 
          description: '' 
          enableClientSsl: false 
          method: GET 
          name: userVpc 
          path: /users 
          retryCount: '-1' 
          scheme: http 
          timeout: 30000 
        parameters: 
          - description: invoke user 
            in: HEADER 
            name: X-Invoke-User 
            origin: CONSTANT 
            value: apigateway 
        type: HTTP-VPC 
      x-apigateway-cors: true 
   
      x-apigateway-match-mode: SWA 
      x-apigateway-request-type: public 
components: 
  responses: 
    default-cors: 
      description: response example 
      headers: 
        Access-Control-Allow-Origin: 
          schema: 
            default: '*' 
            type: string 
  securitySchemes: 
    apig-auth-app: 
      in: header 
      name: Authorization 
      type: apiKey 
      x-apigateway-auth-type: AppSigv1 
    apig-auth-app-header: 
      in: header 
      name: Authorization 
      type: apiKey 
      x-apigateway-auth-opt: 
        appcode-auth-type: header 
      x-apigateway-auth-type: AppSigv1 
    apig-auth-iam: 
      in: header 
      name: unused 
      type: apiKey 
      x-apigateway-auth-type: IAM 
  x-apigateway-responses: {}

導入MOCK類型后端服務API示例

包含無認證的GET方法API定義，后端服務類型為MOCK。

Swagger示例：

swagger: "2.0" 
info: 
  title: "importMockEndpoint" 
  description: "import apis" 
  version: "1.0" 
host: "api.account.com" 
paths: 
  '/mock': 
    get: 
      operationId: "mock" 
      description: "mock test" 
      schemes: 
      - http 
      responses: 
        "200": 
          description: "mock result" 
      x-apigateway-request-type: "private" 
      x-apigateway-cors: true 
   
      x-apigateway-match-mode: "NORMAL" 
      x-apigateway-backend: 
        type: "MOCK" 
        mockEndpoints: 
          result-content: "{\"message\": \"mocked\"}" 
securityDefinitions: 
  apig-auth-app: 
    in: header 
    name: Authorization 
    type: apiKey 
    x-apigateway-auth-type: AppSigv1 
  apig-auth-iam: 
    in: header 
    name: unused 
    type: apiKey 
    x-apigateway-auth-type: IAM

OpenAPI示例：

openapi: 3.0.0 
info: 
  description: import apis 
  title: importHttpVpcEndpoint 
  version: '1.0' 
servers: 
  - url: >- 
      //abc.com 
  - url: >- 
      //abc.com 
paths: 
  /mock: 
    get: 
      description: mock test 
      operationId: mock 
      responses: 
        default-cors: 
          description: response example 
          x-apigateway-result-failure-sample: '' 
          x-apigateway-result-normal-sample: '' 
      servers: 
        - url: >- 
            //abc.com 
      x-apigateway-backend: 
        mockEndpoints: 
          description: '' 
          result-content: '{"message": "mocked"}' 
        type: MOCK 
      x-apigateway-cors: true 
   
      x-apigateway-match-mode: NORMAL 
      x-apigateway-request-type: private 
      x-apigateway-response: default 
components: 
  responses: 
    default-cors: 
      description: response example 
      headers: 
        Access-Control-Allow-Origin: 
          schema: 
            default: '*' 
            type: string 
  securitySchemes: 
    apig-auth-app: 
      in: header 
      name: Authorization 
      type: apiKey 
      x-apigateway-auth-type: AppSigv1 
    apig-auth-app-header: 
      in: header 
      name: Authorization 
      type: apiKey 
      x-apigateway-auth-opt: 
        appcode-auth-type: header 
      x-apigateway-auth-type: AppSigv1 
    apig-auth-iam: 
      in: header 
      name: unused 
      type: apiKey 
      x-apigateway-auth-type: IAM 
  x-apigateway-responses: 
    default: {}