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 Debug the API.
Log on to the API Gateway console.
In the left-side navigation pane, choose Manage APIs > 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.
ImportantThe 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.
NoteIf 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.
NoteBackend 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:
ImportantEach method allows you to import up to 100 API definitions at the same time.
Text: Enter the API definitions in the YAML or JSON format. The API definitions can be up to 256 KB in length.
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.
NoteWarnings: 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
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
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.
Schemes: the request protocols in the API definition.
Path Item Object
Path: the request path in the API definition.
Method: the request method in the API definition. Valid values: GET, POST, PUT, HEAD, DELETE, PATCH, and OPTIONS.
Operation Object
Summary: the description of the API definition.
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.
Schemes: the request protocols in the API definition. Schemes in Operation Object takes precedence over Schemes in Swagger Object.
Parameter Object
Name: the name of the request parameter in the API definition.
In: the location of the request parameter in the API definition. Valid values: path, query, head, and formdata.
Description: the description of the request parameter in the API definition.
Required: specifies whether the request parameter in the API definition is required.
Type: the type of the request parameter in the API definition.
Valid values if you set In to query, path, or head: string, number, integer, boolean, and array.
Valid values if you set In to formdata: string, number, integer, boolean, array, and file.
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
NoteIf 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.
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.
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
HTTP Status Code: the HTTP status code that is contained in the error code definition of the response defined in the API definition.
Description: the description in the error code definition in the sample response in the API definition.
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
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
Path: the request path in the API definition.
Method: the request method in the API definition. Valid values: GET, POST, PUT, HEAD, DELETE, PATCH, and OPTIONS.
Operation Object
Summary: the description of the API definition.
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
Name: the name of the request parameter in the API definition.
In: the location of the request parameter in the API definition. Valid values: path, query, head, and formdata.
Required: specifies whether the request parameter in the API definition is required.
Schema Object
Description: the description of the request parameter in the API definition.
Type: the type of the request parameter in the API definition.
Valid values if you set In to query, path, or head: string, number, integer, boolean, and array.
Valid values if you set In to formdata: string, number, integer, boolean, array, and file.
Format: the format of the request parameter in the API definition. Format takes precedence over Type.
Request Body Object
Content
application/x-www-form-urlencoded: the formdata parameters in the API definition.
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
HTTP Status Code: the HTTP status code that is contained in the error code definition of the response defined in the API definition.
Description: the description in the error code definition in the sample response in the API definition.
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 APIs based on OAS.