Updated on 2022-02-21 GMT+08:00

Restrictions and Compatibility

Note the following restrictions and compatibility issues when importing or exporting APIs on API Gateway:

  • Only Swagger 2.0 is supported.
  • The request parameter types in Swagger 2.0 differ from those on API Gateway. See the following table.
    Table 1 Differences in request parameter types

    Swagger Parameter Type

    API Gateway Parameter Type

    Supported Attribute

    integer

    long

    float

    double

    number

    maximum

    minimum

    default

    enum

    required

    description

    string

    string

    maxLength

    minLength

    default

    enum

    required

    description

    Others

    -

    -

  • API Gateway does not support the configuration of request parameters in the formData and body locations.
  • The names of header parameters are not case-sensitive.
  • API Gateway does not support the configuration of parameters consumes and produces.
  • Imported and exported Swagger objects are mapped to API Gateway objects, as shown in the following table.

    Swagger Object

    API Gateway Object

    Import

    Export

    info.title

    API group name

    Importing to a new API group: a new API group name

    Importing to an existing API group: not used

    An API group name consists of 3–64 characters, starting with a letter. Only letters, digits, and underscores (_) are allowed.

    API group name

    info.description

    API group name

    Importing to a new API group: a new API group name

    Importing to an existing API group: not used

    API group description

    info.version

    API group name

    Not used

    User-defined API group name

    The current time is used as the API group name if no name is specified.

    host

    -

    Not used

    The first user-defined domain name of an API group is preferentially used.

    The independent domain name of the API group is used if the API group is not bound with any user-defined domain names.

    basePath

    -

    Merged with the request path of each API

    Not used

    paths.path

    API request path

    Merged with basePath to use as an API request path

    API request path

    operation.operationId

    API name

    API name

    API name

    operation.description

    API description

    API description

    API description

    operation.parameters

    API frontend request parameters

    API request parameters

    API request parameters

    operation.schemes

    API frontend request protocol

    API request protocol

    API request protocol

    operation.responses

    -

    Not used

    Default response

    operation.security

    API authentication mode

    API authentication mode

    Used together with x-apigateway-auth-type

    API authentication mode

    Used together with x-apigateway-auth-type

  • API request paths differ between Swagger and API Gateway. See the following table.

    Syntax

    Swagger

    API Gateway

    /users/{userName}

    Supported

    Supported

    /users/prefix-{userName}

    /users/{userName}-suffix

    /users/prefix-{userName} -suffix

    Supported

    Not supported for frontend request definition

    Supported for backend request definition

    /users/{proxy+}

    Not supported

    Supported for frontend request definition

    Not supported for backend request definition

  • API Gateway supports the following extended fields when importing APIs:
    • x-apigateway-auth-type
    • x-apigateway-request-type
    • x-apigateway-match-mode
    • x-apigateway-cors
    • x-apigateway-any-method
    • x-apigateway-backend
      • x-apigateway-backend.parameters
      • x-apigateway-backend.httpEndpoints
      • x-apigateway-backend.httpVpcEndpoints
      • x-apigateway-backend.functionEndpoints
      • x-apigateway-backend.mockEndpoints
    • x-apigateway-backend-policies
      • x-apigateway-backend-policies.conditions
    • x-apigateway-ratelimit
    • x-apigateway-ratelimits
      • x-apigateway-ratelimits.policy
      • x-apigateway-ratelimits.policy.special
    • x-apigateway-access-control
    • x-apigateway-access-controls
      • x-apigateway-access-controls.policy
  • Backend policy restrictions are as follows:
    • Default backend type HTTP: The HTTP and HTTP-VPC backends are supported.
    • Default backend type HTTP-VPC: The HTTP and HTTP-VPC backends are supported.
    • Default backend type function: Only the function backend is supported.
    • Default backend type mock: Only the mock backend is supported.