广告位

Api网关通过导入Swagger文件创建和更新Api的功能已经上线了，更多帅气功能会逐步推出
Api网关目标是让您发布应用更加便捷和安全，让您更直观、便捷的管理和调试您的所有Api接口
欢迎试用阿里云Api网关产品，任何问题可以加Ding群讨论：11747055

1. 什么是swagger

微服务现在在商业引用程序开发中，已经广泛使用。而Api作为连接微服务之间的桥梁扮演着至关重要的角色。如何可以更清晰的描述微服务接口、如何可以更便捷便捷的管理Api，已经成为开发人员呼声很高的需求。而作为设计和管理api的利器，Swagger也随之成为了热门。

Swagger出现在2010年，它设计的初衷在于制定一种简单的规范，用于设计Api。Swagger文件可用于开发人员后期维护和管理。随着不断的发展，基于swagger规范，已经衍生出很多工具，用于辅助创建和管理Swagger文件，并已经形成了Swagger生态。用户可以通过Swagger工具来对api的整个生命周期进行设计，管理以及测试等操作。Swagger规范现在已经改名为Openapi规范，它将作为一种定义api管理的规范不断的完善与发展。

2. Api网关的定位

Api网关产品，可以为企业和个人提供完成的API托管服务。用户可以直接使用Api网关提供的认证、流控和监控等功能而无需自行开发。这样，用户就可以更专注于开发和实现自己的后端业务系统，而省去很多系统通用但是不可或缺的功能组件的开发工作。

接入Api网关通常需要如下步骤：

1. 定义Api基本属性，如Api名称，认证方式，基本描述等。
2. 配置Api访问相关属性，用于设置暴露给第三方的访问参数等
3. 配置APi后端相关属性，用于设置真正的后端服务地址，以及参数信息，超时时间等

通过这些配置，就可以完成api在Api网关的接入工作了。具体参考官方文档：Api网关使用须知

3. Swagger基于阿里云Api网关的扩展

与Swagger相同，阿里云Api网关具备Api管理的功能。除此之外，Api网关提供了身份认证，防重放，请求加密以及流量控制等功能。对于用户而言，如果可以将本地用Swagger管理的Api托管至Api网关，在一定程度将会有很大的增益。

因为Swagger与Api网关的定位不同，原生的Swagger文件并不能够直接导入Api网关用来创建Api。详细来说，Swagger通常用于定义和管理真实的服务Api，所以其定义的“访问相关属性”均为服务实际Api的属性，如服务的地址以及传入的参数。因此，Swagger并无类似于“Api后端相关”的属性。而对于Api网关，参数映射及后端服务地址保护是其不可或缺的特性。对此，阿里云Api网关实现了一些Swagger扩展，让用户只需对原生swagger进行简单修改，便能够将其swagger管理的api托管至Api网关进行管理，并享有Api网关提供的所有功能特性。

Swagger扩展主要是对于swagger原生Operation Object进行扩展，增加认证、参数映射以及后端服务等扩展。所有扩展均以x-aliyun-apigateway-开头，具体扩展内容如下：

3.1 x-aliyun-apigateway-auth-type: 授权类型

授权类型，应用于Operation Object。用于指定该API的授权类型，其中：

取值范围:

• APP(默认值): 阿里云API网关APP授权
• ANONYMOUS: 匿名

示例：

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-auth-type: ANONYMOUS
...

3.2 x-aliyun-apigateway-paramater-handling: API映射关系

API映射关系, 应用于Operation Object，用于指定请求参数与后端服务参数的映射关系。当映射关系选择PASSTHROUGH时，Parameter Object不支持 x-aliyun-apigateway-backend-location 和 x-aliyun-apigateway-backend-name 属性。

取值范围:

• PASSTHROUGH(默认值): 入参透传
• MAPPING: 入参映射

示例：

...
paths:
  'path/':
    get:
      x-aliyun-apigateway-paramater-handling: MAPPING
...

3.3 x-aliyun-apigateway-backend: 后端类型

后端类型, 应用于Operation Object。用于设置后端服务信息。根据后端服务类型，决定具体的属性，详情如下：

1.3.1 后端服务类型:HTTP

HTTP的后端类型用于直接配置后端服务地址，一般用于后端地址可以直接访问的场合。

属性说明:

示例:

...
x-aliyun-apigateway-backend:
  type: HTTP
  address: http://10.10.100.2:8000
  path: "/users/{userId}"
  method: GET
  timeout: 7000
...

3.3.2 后端服务类型:HTTP-VPC

HTTP-VPC的后端类型用于后端服务在VPC网络内的场合，需要先创建VPC授权，使用VPC授权名导入。

属性说明:

示例:

...
x-aliyun-apigateway-backend:
  type: HTTP_VPC
  vpcAccessName: vpcAccess1
  path: "/users/{userId}"
  method: GET
  timeout: 10000
...

3.3.3 后端服务类型: MOCK

MOCK的后端类型，用来模拟最初预定的返回结果。

属性说明:

Header 的 说明

示例:

...
x-aliyun-apigateway-backend:
  type: MOCK
  mockResult: mock resul sample
  mockStatusCode ：200
  mockHeaders ：
     - name : server
       value : mock
     - name : proxy
       value : GW
...

3.4 x-aliyun-apigateway-constant-parameters: 常量参数

常量参数, 应用于Operation Object，用于定义后端服务的常量参数。

属性说明:

示例:

      ...
      x-aliyun-apigateway-constant-parameters:
        - backendName: swaggerConstant
          value: swaggerConstant
          location: header
          description: description of swagger
      ...

3.5 x-aliyun-apigateway-system-parameters： 后端服务参数

后端服务参数, 应用于Operation Object，用于定义API后端服务的系统参数。

属性说明:

示例:

    ...
    x-aliyun-apigateway-system-parameters:
        - systemName: CaAppId
          backendName: appId
          location: header
   ...

3.6 x-aliyun-apigateway-backend-location: 后端参数位置

后端参数位置, 应用于 Parameter Object。该属性仅在 x-aliyun-apigateway-paramater-handling: MAPPING设置时生效，用于设置参数映射后，在后端服务请求时的参数位置。

取值范围:

• path
• header
• query
• formData

示例:

     ...
      parameters:
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
      ...

3.7 x-aliyun-apigateway-backend-name: 后端参数名称

后端参数名称, 应用于Parameter Object。该属性仅在 x-aliyun-apigateway-paramater-handling: MAPPING设置时生效，用于设置参数映射后，在后端服务请求时的参数名称。

示例:

      ...
      parameters:
        - name: swaggerHeader
          in: header
          required: false
          type: number
          format: double
          minimum: 0.1
          maximum: 0.5
          x-aliyun-apigateway-backend-location: query
          x-aliyun-apigateway-backend-name: backendQuery
      ...

4. 基于阿里云api网关扩展的Swagger示例

第三节我们对Api网关的Swagger扩展进行了介绍，这里我们提供一个后端服务为Mock类型的示例帮助用户对Swagger文件的配置有更明确的了解

swagger: '2.0'
basePath: /
info:
  version: '0.9'
  title: Aliyun Api Gateway Swagger Sample
schemes:
  - http
paths:
  '/mock/get/mapping/{userId}':
    get:
      operationId: case1
      schemes:
        - http
        - https
      x-aliyun-apigateway-paramater-handling: MAPPING
      x-aliyun-apigateway-backend:
        type: MOCK
        mockResult: mock resul sample
        mockStatusCode ：200
        mockHeaders ：
          - name : server
            value : mock
          - name : proxy
            value : GW
      parameters:
        - name: userId
          in: path
          required: true
          type: string
      responses:
        '200':
          description: 200 description
        '400':
          description: 400 description

5. 通过导入Swagger创建和更新Api

Api网关可以通过两种方式导入Swagger并创建或者更新Api，分别为：Aliyun Openapi导入和web控制台导入。

5.1 ImportSwagger接口使用

通过调用ImportSwagger接口，可以通过导入符合阿里云swagger规范的文本内容创建API：

请求参数

返回参数

对象说明

ApiImportSwaggerSuccess

ApiImportSwaggerFailed

5.2 通过Web控制台导入Swagger

在Api管理界面，我们可以找到导入Swagger的入口，见下图:

点击导入Swagger进入Swagger导入界面，按照填写相应信息就可以完成Swagger的导入工作。控制台右方会返回最终api的创建结果：

6. 总结

以上就是阿里云Api网关对swagger文件的支持情况。现在用户可以通过配置基于Aliyun Api网关扩展的Swagger文件创建Api，可以方便的将本地Swagger文件管理的api托管至Api网关管理。但当前Swagger扩展并不能完全覆盖Api网关的所有功能，后续还会进行完善和升级，提高更好的便利性和友好度。

Reference