更新时间:2024-05-24 GMT+08:00

导入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设计文件

导入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-is-send-fg-body-base64: 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-is-send-fg-body-base64: 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-is-send-fg-body-base64: 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-is-send-fg-body-base64: 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: {}

导入FUNCTION类型后端服务API示例

包含IAM认证和请求参数编排的GET方法API定义,后端服务类型为FunctionGraph。

Swagger示例:

swagger: "2.0"
info:
  title: "importFunctionEndpoint"
  description: "import apis"
  version: "1.0"
host: "api.account.com"
paths:
  '/function/{name}':
    get:
      operationId: "invokeFunction"
      description: "invoke function by name"
      security:
      - apig-auth-iam: []
      schemes:
      - https
      parameters:
      - name: "test"
        description: "authorization token"
        type: "string"
        in: "header"
        required: true
      - name: "name"
        description: "function name"
        type: "string"
        in: "path"
        required: true
      responses:
        "200":
          description: "function result"
      x-apigateway-request-type: "public"
      x-apigateway-cors: true
      x-apigateway-is-send-fg-body-base64: true
      x-apigateway-match-mode: "NORMAL"
      x-apigateway-backend:
        type: "FUNCTION"
        parameters:
        - name: "functionName"
          value: "name"
          in: "query"
          origin: "REQUEST"
          description: "function name"
        - name: "X-Invoke-User"
          value: "apigateway"
          in: "header"
          origin: "CONSTANT"
          description: "invoke user"
        functionEndpoints:
          function-urn: "your function urn address"
          version: "your function version"
          invocation-type: "async"
          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: importHttpEndpoint
  version: '1.0'
servers:
  - url: >-
      http://api.account.com
  - url: >-
      https://api.account.com
paths:
  /function/{name}:
    get:
      description: invoke function by name
      operationId: invokeFunction
      parameters:
        - description: function name
          in: path
          name: name
          required: true
          schema:
            maxLength: 0
            maximum: 0
            minimum: 0
            type: string
          x-apigateway-pass-through: always
          example: ''
        - description: authorization token
          in: header
          name: test
          required: true
          schema:
            maxLength: 0
            maximum: 0
            minimum: 0
            type: string
          x-apigateway-pass-through: always
          example: ''
      responses:
        default-cors:
          description: response example
          x-apigateway-result-failure-sample: ''
          x-apigateway-result-normal-sample: ''
      security:
        - apig-auth-iam: []
      servers:
        - url: >-
            https://api.account.com
      x-apigateway-backend:
        functionEndpoints:
          alias-urn: ''
          description: ''
          function-urn: "your function urn address"
          invocation-type: async
          network-type: V1
          timeout: 30000
          version: "your function version"
        parameters:
          - description: invoke user
            in: HEADER
            name: X-Invoke-User
            origin: CONSTANT
            value: apigateway
          - description: function name
            in: QUERY
            name: functionName
            origin: REQUEST
            value: name
        type: FUNCTION
      x-apigateway-cors: true
      x-apigateway-is-send-fg-body-base64: 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-iam:
      in: header
      name: unused
      type: apiKey
      x-apigateway-auth-type: IAM
  x-apigateway-responses:
    default: {}

导入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-is-send-fg-body-base64: 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-is-send-fg-body-base64: 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: {}

后续操作

将导入成功的API发布到环境中,以便API调用者调用。