导出标准OAS定义

概述

本文主要介绍了API网关可以将API资源导出为标准OAS定义，结合API网关的导入标准OAS定义，您可以：

1. 跨平台跨地域迁移数据：借助API网关的导出和导入功能，您可以方便地从其他平台或API网关导出OAS规范的API数据，并在其他地域或账号下实现API的快速导入，简化您迁移的过程；

2. API发布与扩展：通过将使用标准OAS规范的API定义转化为API网关的API资源，您能够快速在API网关创建和配置API，然后根据您的需求，自定义和扩展API的功能和行为。通过API网关的灵活性，您可以更好地管理和控制API的访问权限、流量限制和请求转发，提供高度可靠和安全的API服务。

3. 整合与协作：通过将API导出为标准OAS规范的API定义，您可以方便地与其他开发工具或平台进行集成。这样，您可以与团队成员或第三方开发者更好地协作，共享API资源的详细信息，减少沟通成本和开发时间。

导出标准OAS格式的API定义

导出API定义支持以分组为单位进行API导出，也支持通过批量勾选API进行导出

操作步骤

1. 通过分组导出API定义

   1. 登录API网关控制台。

   2. 在控制台左侧菜单中，选择开放API > 分组管理。

   3. 在API分组列表页面中，在要导出的API分组的操作栏中选择更多 > 导出API定义。

   4. 在弹出框中指定导出的数据格式，环境以及是否需要导出API网关扩展字段。

2. 直接导出API定义

   1. 登录API网关控制台。

   2. 在控制台左侧菜单中，选择开放API > API列表。

   3. 在API列表页面中，勾选需要导出的API，然后单击下方的导出API定义。

   4. 在弹出框中指定导出的数据格式，环境以及是否需要导出API网关扩展字段。

API网关扩展定义说明

如果在导出OAS规范的定义中选择了导出API网关扩展字段，在导出的API定义文件中会添加网关的扩展字段。

说明

1. 以分组为单位导出时，会导出分组的base path；

2. 每次可以导出的API数量限制为300个API，若超出限制默认导出分组下前300个API；

3. 分组模型管理里中定义的模型定义如果无法解析，导出的内容中将不包含模型定义；

4. 以API为单位导出时，所有勾选的API会导出到一个文件中；

5. 以API为单位导出时，如果存在API有相同的path和method，只会导出其中一个；

6. 未勾选导出API网关扩展字段时，导出OAS文件中的OperationId为API定义的请求path和请求method的拼接后的字符串，如“export1ByGET”；

7. 勾选导出API网关扩展字段后，在API网关定义API以外的内容，如绑定的插件、授权的APP、分组的域名、后端服务在各环境上的定义等，均不会导出。

示例

如下为使用API网关提供的分组导出带有扩展定义的OAS2.0内容：

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: 测试导出1
      operationId: export1pathParamByGET
      schemes:
        - http
        - https
      parameters:
        - name: pathParam
          in: path
          description: 测试path参数
          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: 测试head参数
          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: 测试query参数
          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: 成功
          x-aliyun-apigateway-response-messages: success
        '400':
          description: 客户端错误
          x-aliyun-apigateway-response-messages: clent error
        '500':
          description: 服务端错误
          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: 测试常量参数
      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: 测试导出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: 测试常量参数
      x-aliyun-apigateway-system-parameters:
        - backendName: testClientIp
          systemName: CaClientIp
          location: header
      responses:
        '200':
          description: 成功
          briefMessage: success
          schema:
            $ref: testModel
        '400':
          description: 客户端错误
          briefMessage: clent error
          schema:
            $ref: testModel
        '500':
          description: 服务端错误
          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