API Gateway:Export APIs based on OAS

Overview

This topic describes how to export APIs from API Gateway based on the OAS standard. The following items describe the things that you can do by using this feature in combination with the API import feature of API Gateway. For more information about the API import feature, see Import OAS-compliant APIs.

1. Migrate APIs across accounts, regions, or platforms: You can easily export OAS-compliant APIs from API Gateway or another platform and then import these APIs to instances of another Alibaba Cloud account or region or another platform.

2. Publish and extend APIs: You can convert OAS-compliant API definitions into API resources in API Gateway. This allows you to quickly create, configure, and then customize or extend the functions and behavior of APIs based on your needs. The flexibility of API Gateway helps you manage API access permissions, throttle traffic, and forward requests in a reliable and secure manner.

3. Integrate and collaborate: You can easily integrate your exported APIs with other development tools or platforms based on the OAS standard. This way, you can better collaborate with your team or other developers because API sharing reduces communication and development workloads.

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 Open API > API Groups.

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

   4. In the dialog box that appears, 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 Open API > APIs.

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

   4. In the dialog box that appears, 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, extended fields relating to API Gateway are added to the exported API files. The following table describes the fields.

Note

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

In the following sample code, an API group and its extended API definitions are exported.

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