Export APIs based on OAS

Overview

You can export APIs from API Gateway in OAS format. Combined with the API import feature, this enables the following scenarios. For more information about the API import feature, see Import OAS-compliant APIs.

1. Migrate APIs across accounts, regions, or platforms: Export OAS-compliant APIs from API Gateway or another platform, and then import them into a different Alibaba Cloud account, region, or platform.

2. Publish and extend APIs: Convert OAS-compliant API definitions into API resources in API Gateway to quickly create and configure APIs, then customize their behavior as needed. API Gateway helps you manage access permissions, throttle traffic, and forward requests securely.

3. Integrate and collaborate: Integrate exported APIs with other development tools or platforms based on the OAS standard. Sharing API definitions reduces communication overhead and development effort across teams.

Export OAS-compliant APIs

You can export an entire API group or specific APIs.

Procedure

1. Export an API group

   1. Log on to the API Gateway console.

   2. In the left-side navigation pane, choose Manage APIs > API Groups.

   3. On the API Groups page, find the API group that you want to export. Click and then choose Export API Definitions in the Actions column.

   4. In the Export API Definitions dialog box, specify the Data Format, Stage, and Export Extended Definitions parameters. Then, click Confirm.

2. Export specific APIs

   1. Log on to the API Gateway console.

   2. In the left-side navigation pane, choose Manage APIs > APIs.

   3. On the APIs page, select the APIs that you want to export and choose More > Export API Definitions below the list.

   4. In the Export API Definitions dialog box, specify the Data Format, Stage, and Export Extended Definitions parameters. Then, click Confirm.

Extended API definitions

If you select Yes for the Export Extended Definitions parameter, the following API Gateway-specific fields are added to the exported files.

Description

1. If you export by group, the base path of the group is exported.

2. You can export up to 300 APIs at a time. If the group to be exported contains more than 300 APIs, the first 300 APIs are exported.

3. If the model definition of an API group cannot be parsed, the model definition is not exported.

4. If you export specific APIs, all selected APIs are exported to the same file.

5. If APIs have the same path and method, only one of the APIs is exported.

6. If you select No for the Export Extended Definitions parameter, the OperationId value in the exported file is a concatenated string of the request path and request method of the API definition, such as export1ByGET.

7. If you select Yes for the Export Extended Definitions parameter, the additional information about the API, such as its bound plug-in, authorized application, bound domain name of the API group, and backend service definitions in different environments, is not exported.

Example

The following example shows an exported API group with extended API definitions.

swagger: '2.0'
info:
  description: Export from api group xxx
  version: 1.0.0
  title: Api Gateway API
basePath: /export
paths:
  /export1/{pathParam}:
    get:
      summary: test export job 1.
      operationId: export1pathParamByGET
      schemes:
        - http
        - https
      parameters:
        - name: pathParam
          in: path
          description: the path parameter.
          required: true
          type: string
          maxLength: 10
          x-aliyun-apigateway-parameter-demo: pathValue
          x-aliyun-apigateway-backend-name: pathParam
          x-aliyun-apigateway-backend-location: path
        - name: headParam
          in: header
          description: the header parameters.
          required: false
          type: string
          x-aliyun-apigateway-parameter-demo: headerValue
          x-aliyun-apigateway-backend-name: headParam
          x-aliyun-apigateway-backend-location: query
        - name: queryParam
          in: query
          description: the query parameters.
          required: false
          type: string
          x-aliyun-apigateway-parameter-demo: queryValue
          x-aliyun-apigateway-backend-name: queryParam
          x-aliyun-apigateway-backend-location: header
      responses:
        '200':
          description: success.
          x-aliyun-apigateway-response-messages: success
        '400':
          description: client error.
          x-aliyun-apigateway-response-messages: clent error
        '500':
          description: server error.
          x-aliyun-apigateway-response-messages: server error
      x-aliyun-apigateway-system-parameters:
        - backendName: testClientIp
          systemName: CaClientIp
          location: header
      x-aliyun-apigateway-constant-parameters:
        - backendName: constantparam
          location: header
          value: constantValue
          descriptoin: the constant parameters.
      x-aliyun-apigateway-api-name: export_1
      x-aliyun-apigateway-api-market-enable: false
      x-aliyun-apigateway-api-force-nonce-check: true
      x-aliyun-apigateway-parameter-handling: MAPPING
      x-aliyun-apigateway-auth-type: APP
      x-aliyun-apigateway-api-enable-internet: true
      x-aliyun-apigateway-failed-demo: '{"result":"fail"}'
      x-aliyun-apigateway-success-demo: '{"result":"success"}'
      x-aliyun-apigateway-app-code-type: DEFAULT
      x-aliyun-apigateway-backend:
        body: good job
        statusCode: 200
        header:
          - name: test
            value: header1
        type: MOCK
  /export2/*:
    x-aliyun-apigateway-any-method:
      operationId: export_2
      description: test export job 1.
      x-aliyun-apigateway-api-market-enable: false
      x-aliyun-apigateway-api-force-nonce-check: false
      x-aliyun-apigateway-api-enable-internet: true
      x-aliyun-apigateway-parameter-handling: PASSTHROUGH
      x-aliyun-apigateway-auth-type: ANONYMOUS
      x-aliyun-apigateway-success-demo: '{"result":"success"}'
      x-aliyun-apigateway-failed-demo: '{"result":"fail"}'
      schemes:
        - http
        - https
      x-aliyun-apigateway-backend:
        body: good job
        statusCode: 200
        header:
          - name: test
            value: header1
        type: MOCK
      x-aliyun-apigateway-constant-parameters:
        - backendName: constantparam
          location: header
          value: constantValue
          descriptoin: the constant parameters.
      x-aliyun-apigateway-system-parameters:
        - backendName: testClientIp
          systemName: CaClientIp
          location: header
      responses:
        '200':
          description: success.
          briefMessage: success
          schema:
            $ref: testModel
        '400':
          description: client error.
          briefMessage: clent error
          schema:
            $ref: testModel
        '500':
          description: server error.
          briefMessage: server error
definitions:
  testModel:
    type: object
    required:
      - name
    properties:
      dogProject:
        type: object
        properties:
          name:
            type: string
            maxLength: 10
          id:
            type: integer
            format: int64
      name:
        type: string
        pattern: ^\d{3}-\d{2}-\d{4}$
      id:
        type: integer
        format: int64
      status:
        type: string