How to import multiple OAS-compliant APIs at a time - API Gateway

API Gateway allows you to import API definitions that follow the OpenAPI Specification (OAS) 2.0 or 3.0 standard. For more information about OAS, see OpenAPI Specification. You can import OAS-compliant API definitions or import OAS-compliant API definitions that contain API Gateway extensions.

Import OAS-compliant API definitions

Process:

Specify the API group to which you want to import the APIs and configure global settings.
Enter OAS 2.0-compliant or OAS-3.0 compliant API definitions.
Precheck the API definitions and fix issues based on the precheck results.
Import the API definitions.

After the API definitions are imported, the APIs are created in the specified API group. Then, you can publish the APIs to the environment of your choosing and debug the APIs. For more information, see the "Debug the API" section of the Create an API topic.

Log on to the API Gateway console.
In the left-side navigation pane, choose Open API > APIs.
On the APIs page, click Import Swagger-compliant Data.

In the Note dialog box, click Standard OAS to go to the Import Swagger-compliant Data page.

In the Basic Information section, configure the following parameters.

Parameter	Description
Import to Group	Specify the API group to which you want to import the APIs. Important The base path of the API group must be the same as the base path in your OAS-compliant API definitions. Otherwise, the definitions fail to be imported. For more information about the base path of the API group, see Create an API group. For more information about the base path in OAS, see Swagger Object.
Overwrite	If you select the checkbox and the request path conflicts with the HTTP request, the existing API is overwritten. If you do not select the checkbox and the request path conflicts with the HTTP request, an error message that indicates the API already exists is returned.
API Definition Version	OAS 2.0 and OAS 3.0 are supported.

In the (Optional) Global Configurations section, configure global settings for the APIs.

Parameter	Description
Backend Service	Specify a backend service of the HTTP/HTTPS, VPC, Mixed, or Service discovery type that is created in API Gateway. The default value is Mock. For more information, see Use a backend service to create and manage APIs.
Request Mode	Set this parameter to Pass-through or Map (Filter Out Unknown Parameters). The default value is Pass-through. Note If you use the pass-through request mode, only the path parameter is imported. API Gateway ignores the other parameters, including the query, header, formdata, and body parameters.
Caller Authentication	Set this parameter to Alibaba Cloud App or No Authentication. The default value is Alibaba Cloud App. Note Backend service, request mode, and caller authentication are global settings that take effect for all APIs. If you use the extensions that are supported by API Gateway to declare the settings in OAS 2.0-complinant API definitions, the settings are prioritized in the following order: OAS 2.0-complinant API definitions, OAS global definitions, and optional global settings of API Gateway. For more information about the extensions, see the "Import OAS-compliant API definitions that contain API Gateway extensions" section of this topic. AppCode Authentication: The default value is Disable AppCode Authentication if you set Caller Authentication to Alibaba Cloud App. Signature Algorithm: The default value is HMAC_SHA256.

In the API Definition section, enter the OAS 2.0-complinant API definitions and specify one of the following import methods:
Important
Each method allows you to import up to 100 API definitions at the same time.
1. Text: Enter the API definitions in the YAML or JSON format. The API definitions can be up to 256 KB in length.
2. OSS URL: Enter the URL of the Object Storage Service (OSS) object in which the API definitions are stored. The object must be in the JSON or YAML format. The object URL must support anonymous access. No limit is imposed on the object size.

Determine whether to modify the default settings of other parameters in the API definitions. These parameters are configured when you import the API definitions, but are not provided on the Import Swagger-compliant Data page. The following table describes the parameters:

Parameter	Description
Anti-replay Protection	By default, this feature is disabled.
Forbid Internet Access	By default, this feature is disabled.
Allow API Publish to Alibaba Cloud Marketplace	By default, this feature is disabled.

Click Precheck. API Gateway performs a dry run on the data that you want to import and returns the API definitions and model definitions in OAS-compliant API definitions, the warnings, and the errors.
Note
Warnings: Before you import the API definitions, you can ignore the warnings. In this case, the API definitions that contain the warnings are ignored.
Errors: You must fix errors. Otherwise, an exception is thrown.
Confirm that no errors and warnings exist and click Import Swagger-compliant Data to import the APIs. This process may take some time. Do not close your browser before the import is complete.
After the APIs are imported, you can view the import result of the APIs.

Mappings between the parameters in an OAS 2.0-complinant API definition and an API Gateway API definition

Note

This section describes only the parameters in an OAS 2.0-complinant API definition that can be mapped to the parameters in an API definition of API Gateway. If a parameter in an OAS 2.0-complinant API definition cannot be mapped to API Gateway, the import of the API is not affected.

Swagger Object
1. BasePath: the base path of the API group. When you import an API definition, API Gateway checks whether the base path of the API definition is the same as the base path of the API group.
2. Schemes: the request protocols in the API definition.
Path Item Object
1. Path: the request path in the API definition.
2. Method: the request method in the API definition. Valid values: GET, POST, PUT, HEAD, DELETE, PATCH, and OPTIONS.
Operation Object
1. Summary: the description of the API definition.
2. OperationId: the name of the API that corresponds to the API definition. If the extension field x-aliyun-apigateway-api-name exists, the name in the extension field is used as the name of the API.
3. Schemes: the request protocols in the API definition. Schemes in Operation Object takes precedence over Schemes in Swagger Object.
Parameter Object
1. Name: the name of the request parameter in the API definition.
2. In: the location of the request parameter in the API definition. Valid values: path, query, head, and formdata.
3. Description: the description of the request parameter in the API definition.
4. Required: specifies whether the request parameter in the API definition is required.
5. Type: the type of the request parameter in the API definition.
  1. Valid values if you set In to query, path, or head: string, number, integer, boolean, and array.
  2. Valid values if you set In to formdata: string, number, integer, boolean, array, and file.
6. Format: the format of the request parameter in the API definition. Format takes precedence over Type.
  The following table lists the mappings between the parameter types in OAS and the parameter types in API Gateway.
  Parameter type in OAS
  Parameter type in API Gateway
  String
  String
  Boolean
  Boolean
  Array
  Array
  Int32
  Int
  Int64
  Long
  Double
  Double
  Float
  Float
  File
  File
  Note
  1. If you use the pass-through request mode for an API definition, only the path parameter is imported to the API definition. API Gateway ignores the other parameters, including the query, header, formdata, and body parameters.
  2. If you use the pass-through request mode for an API definition and do not use API Gateway extensions, make sure that the same values are specified for the request method, request path, and parameter definition in the request parameters of the API definition and in the backend service.
  3. If the parameters in the request body are referenced, the parameters are displayed when the document is generated, but not displayed in the API definition of API Gateway.
Response Object
1. HTTP Status Code: the HTTP status code that is contained in the error code definition of the response defined in the API definition.
2. Description: the description in the error code definition in the sample response in the API definition.
3. Schema: the model that is contained in the error code definition of the response defined in the API definition.
Definitions Object
The objects in the API definition. When you import the API definition, API Gateway creates models in the API group that you specify. On the API Groups page, you can click Manage Model in the Actions column of the API group to view the model definitions.

The following sample code provides an example on how to define an OAS 2.0-complinant API definition to help you familiarize yourself with this feature. In this example, the API definition of Swagger Petstore is used.

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"

Mappings between the parameters in an OAS 3.0-complinant API definition and an API Gateway API definition

Note

This section describes the mapped fields between an OAS 3.0-compliant API definition and an API Gateway API definition. Unmapped fields do not affect API imports.

Path Item Object
1. Path: the request path in the API definition.
2. Method: the request method in the API definition. Valid values: GET, POST, PUT, HEAD, DELETE, PATCH, and OPTIONS.
Operation Object
1. Summary: the description of the API definition.
2. OperationId: the name of the API that corresponds to the API definition. If the extension field x-aliyun-apigateway-api-name exists, the name in the extension field is used as the name of the API.
Parameter Object
1. Name: the name of the request parameter in the API definition.
2. In: the location of the request parameter in the API definition. Valid values: path, query, head, and formdata.
3. Required: specifies whether the request parameter in the API definition is required.
Schema Object
1. Description: the description of the request parameter in the API definition.
2. Type: the type of the request parameter in the API definition.
  1. Valid values if you set In to query, path, or head: string, number, integer, boolean, and array.
  2. Valid values if you set In to formdata: string, number, integer, boolean, array, and file.
3. Format: the format of the request parameter in the API definition. Format takes precedence over Type.
Request Body Object
1. Content
  1. application/x-www-form-urlencoded: the formdata parameters in the API definition.
  2. application/json: For objects defined in this item, API Gateway creates the model in the group during imports. To view the model definition, click Manage Model in the Actions column in the row that contains the group in the group list.
Responses Object
1. HTTP Status Code: the HTTP status code that is contained in the error code definition of the response defined in the API definition.
2. Description: the description in the error code definition in the sample response in the API definition.
3. Content: the model in the error code definition in the response defined in the API definition.

The following example shows an OAS 3.0-compliant definition. In this example, the definition of PetStore is used.

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

Import OAS 2.0-complinant API definitions that contain API Gateway extensions

For more information, see Export OAS-compliant APIs.

Parameter type in OAS	Parameter type in API Gateway
String	String
Boolean	Boolean
Array	Array
Int32	Int
Int64	Long
Double	Double
Float	Float
File	File