Automate API Creation by Importing OpenAPI Specs via ImportOAS - API Gateway

Imports OpenAPI Specification (OAS)-compliant data to create an API.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

apigateway:ImportOAS

create

*ApiGroup

acs:apigateway:{#regionId}:{#accountId}:apigroup/{#GroupId}

None

Request parameters

Parameter	Type	Required	Description	Example
GroupId	string	Yes	The ID of the API group.	08ae4aa0f95e4321849ee57f4e0b3077
Data	string	Yes	The OAS-compliant text file or OSS object URL.	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"
Overwrite	boolean	Yes	Specifies whether to overwrite an existing API. If an existing API has the same HTTP request type and backend request path as the API to be imported, the existing API is overwritten.	true
IgnoreWarning	boolean	No	Specifies whether to ignore alerts.	true
SkipDryRun	boolean	No	Specifies whether to directly import the API without performing a precheck.	true
OASVersion	string	No	The OAS version.	OAS2
BackendName	string	No	The name of the backend service.	testBackendService
AuthType	string	No	The security authentication method of the API. Valid values: APP: Only authorized applications can call the API. ANONYMOUS: The API can be anonymously called. In this mode, you must take note of the following rules: All users who have obtained the API service information can call this API. API Gateway does not authenticate callers and cannot set user-specific throttling policies. If you make this API public, set API-specific throttling policies.	APP
RequestMode	string	No	The request mode. Valid values: MAPPING: Parameters are mapped. Unknown parameters are filtered out. PASSTHROUGH: Parameters are passed through.	PASSTHROUGH

Response elements

Element	Type	Description	Example
	object
OperationId	string	The ID of the asynchronous API import task that was generated during the import operation. This ID is used to query the execution status of the API import task.	c16a1880f5164d779f6a54f64d997cd9
RequestId	string	The ID of the request.	E7FE7172-AA75-5880-B6F7-C00893E9BC06
ErrorMessages	object
ErrorMessage	array	The error messages that appear due to the invalid data in the imported file.
	string	The error message that appears due to the invalid data in the imported file.	Invalid extensions:x-aliyun-apigateway-auth-type. Option value [ANONYMOUS, APP].
WarningMessages	object
WarningMessage	array	The warning messages that appear due to the invalid data in the imported file.
	string	The warning message that appears due to the invalid data in the imported file.	There is no valid api definition in your file.
SuccessApis	object
SuccessApi	array<object>	The information about the APIs that have passed the precheck.
	object	The information about the API that has passed the precheck.
Path	string	The request path configured when you created the API.	/st1
HttpMethod	string	The HTTP method configured when you created the API.	POST
ApiId	string	The ID of the API.	92af1abffc2443eaa2b815fdbd9c13f1
ApiOperation	string	Indicates that the operation is CREATE or MODIFY.	CREATE
FailedApis	object
FailedApi	array<object>	The APIs that failed to pass the precheck.
	object	The API that failed to be pass the precheck.
Path	string	The request path configured when you created the API.	/st1
HttpMethod	string	The HTTP method configured when you created the API.	POST
ErrorMsg	string	The error message.	Invalid Api Definition.
FailedModels	object
FailedModel	array<object>	The information about the models that failed to pass the precheck.
	object	The information about the model that failed to pass the precheck.
ErrorMsg	string	The error message.	Invalid Model Definition.
ModelName	string	The name of the model.	test
GroupId	string	The ID of the API group.	2c1bc62e19614cc68c6b0b484bc9c5db
SuccessModels	object
SuccessModel	array<object>	The information about the models that have passed the precheck.
	object	The information about the model that has passed the precheck.
ModelUid	string	The UID of the model.	1r4efwee19614cc68c6b0b484bc9c5dbs
ModelName	string	The name of the model.	test
GroupId	string	The ID of the API group.	feaccf67040643bcbdedb253e59eb527
ModelOperation	string	The operation of the model. Valid values: CREATE and MODIFY.	CREATE

Examples

Success response

JSON format

{
  "OperationId": "c16a1880f5164d779f6a54f64d997cd9",
  "RequestId": "E7FE7172-AA75-5880-B6F7-C00893E9BC06",
  "ErrorMessages": {
    "ErrorMessage": [
      "Invalid extensions:x-aliyun-apigateway-auth-type. Option value [ANONYMOUS, APP]."
    ]
  },
  "WarningMessages": {
    "WarningMessage": [
      "There is no valid api definition in your file."
    ]
  },
  "SuccessApis": {
    "SuccessApi": [
      {
        "Path": "/st1",
        "HttpMethod": "POST",
        "ApiId": "92af1abffc2443eaa2b815fdbd9c13f1",
        "ApiOperation": "CREATE"
      }
    ]
  },
  "FailedApis": {
    "FailedApi": [
      {
        "Path": "/st1",
        "HttpMethod": "POST",
        "ErrorMsg": "Invalid Api Definition."
      }
    ]
  },
  "FailedModels": {
    "FailedModel": [
      {
        "ErrorMsg": "Invalid Model Definition.",
        "ModelName": "test",
        "GroupId": "2c1bc62e19614cc68c6b0b484bc9c5db"
      }
    ]
  },
  "SuccessModels": {
    "SuccessModel": [
      {
        "ModelUid": "1r4efwee19614cc68c6b0b484bc9c5dbs",
        "ModelName": "test",
        "GroupId": "feaccf67040643bcbdedb253e59eb527",
        "ModelOperation": "CREATE"
      }
    ]
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.