操作场景

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: >- 
      http://abc.com 
  - url: >- 
      https://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: >- 
            https://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: >- 
      http://abc.com 
  - url: >- 
      https://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: >- 
            https://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: >- 
      http://abc.com 
  - url: >- 
      https://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: >- 
            http://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: {}