阿里云Api网关导入Swagger功能简介

2018-09-26 629

广告位

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网关通常需要如下步骤：

定义Api基本属性，如Api名称，认证方式，基本描述等。
配置Api访问相关属性，用于设置暴露给第三方的访问参数等
配置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的后端类型用于直接配置后端服务地址，一般用于后端地址可以直接访问的场合。

属性说明:

属性名称	类型	描述
type	string	必填；值为HTTP
address	string	必填；用于标识后端服务地址
path	string	必填:用于标识后端服务路径。支持路径变量
method	string	必填：后端请求方法
timeout	int	选填，默认为10000。该属性取值范围为[500,30000]

示例:

...
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授权名导入。

属性说明:

属性名称	类型	描述
type	string	必填；值为：HTTP-VPC
vpcAccessName	string	必填；后端服务使用的vpc实例名称
path	string	必填:用于标识后端服务路径。支持路径变量
method	string	必填：后端请求方法
timeout	int	选填，默认为10000。该属性取值范围为[500,30000]

示例:

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

3.3.3 后端服务类型: MOCK

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

属性说明:

属性名称	类型	描述
type	string	必填；值为:MOCK
mockResult	string	必填；mock返回结果
mockStatusCode	Integer	选填
mockHeaders	Header	选填

Header 的说明

属性名称	类型	描述
name	string	必填
value	string	必填

示例:

...
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，用于定义后端服务的常量参数。

属性说明:

属性名称	类型	描述
backendName	string	必填；后端参数名称
value	string	必填；常量值
location	String	必填；常量参数存放位置，可选值:[query,header]
description	string	可选；用于对该常量进行说明

示例:

      ...
      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后端服务的系统参数。

属性说明:

属性名称	类型	描述
systemName	string	必填；系统参数名称
backendName	string	必填；后端参数名称
location	String	必填；常量参数存放位置，可选值:[query,header]

示例:

    ...
    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：

请求参数

名称	类型	是否必须	描述
Action	String	是	操作接口名，取值：ImportSwagger
GroupId	String	是	swagger将被导入的分组编号
Overwrite	Boolean	是	是否覆盖现有API。覆盖检测条件为: API的http请求类型+后端请求路径相同
DataFormat	String	是	swagger文本格式： json yaml
Data	String	是	swagger文本内容。详情请查看：通过Swagger导入API

返回参数

名称	数据类型	描述
RequestId	String	本次请求编号
Success	ApiImportSwaggerSuccess	本次所有通过swagger导入成功的API信息
Failed	ApiImportSwaggerFailed	本次所有通过swagger导入失败的API信息

对象说明

ApiImportSwaggerSuccess

对象属性名称	对象属性类型	描述
Path	String	创建API时配置的请求路径
Method	String	创建API时配置的http方法
ApiUid	String	导入成功的API的UID
ApiOperation	String	该API是创建（CREATE）或修改（MODIFY）

ApiImportSwaggerFailed

对象属性名称	对象属性类型	描述
Path	String	创建API时配置的请求路径
Method	String	创建API时配置的http方法
ErrorMsg	String	创建API时返回的错误信息

5.2 通过Web控制台导入Swagger

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

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

6. 总结

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

Reference

微信关注我们

原文链接：https://yq.aliyun.com/articles/645874

转载内容版权归作者及来源网站所有！

低调大师中文资讯倾力打造互联网数据资讯、行业资源、电子商务、移动互联网、网络营销平台。持续更新报道IT业界、互联网、市场资讯、驱动更新,是最及时权威的产业资讯及硬件资讯报道平台。

网站选择什么样配置的服务器合适？

在如今大数据流量剧增的网络应用时代，服务器租用越来越成为众多企业和运营商的首选。而性能和配置不达标的服务器选择只会给企业带来诸多运营问题；但不经过实际需求的评估，轻率的选择一台性能强劲、价格昂贵的服务器，无疑是会带来成本上的浪费；因此，不能一味的为了省钱而选择一台很容易称为计算瓶颈，或者没有充分考虑数据冗余的服务器，都是会影响正常的业务运行，你需要从不同的角度来决定选择一台什么样的服务器，找到满足技术需要、业务发展和成本控制之间的最佳平衡点，为了做到这一点，绝对还是需要一点智慧。阿里云代金券1000元免费领取地址：https://promotion.aliyun.com/ntms/yunparter/invite.html?userCode=2a7uv47d 新老阿里云账户均可领取！可用于购买阿里云服务器ECS、云数据库RDS、虚拟主机、安骑士、DDoS高防IP等100多云计算产品。代金券自领取之日起，有效期是30天，请及时使用，过30天后还可以重新领取。下面为大家介绍一些易于理解，尽可能全面的建议，并帮助你做出决定。先不要急于决定需要怎样的CPU，几个硬盘，几个G内存，需要多...

2018-09-27

785

在如下这两篇篇文章我都或多或少强调过业务分层方面的的方法和注意事项，感兴趣的可以看看: 系统设计和系统划分有定律可循业务拆分的思考之前是说，现在是做。以我个人博客为例，我的博客最初只是一个单体应用，但是我决定将其拆分为多个模块，总体来说，还是一个单体war。但是性质是不一样的。下面进入正题: 贴图说明: blog-parent是父工程 blog-common主要放置工具类和其他可以复用的第三方插件或者是其他功能类 blog-entity 放置实体,通常是pojo也可以叫entity或者javabean blog-dao 放置与数据库交互的接口类，也就是mapper blog-service 业务接口及其实现类 blog-web 前台展示同时如果还开发安卓应用的话，直接提供接口 blog-generator 是代码生成器，主要应用于个人开发，提高效率用的上述的依赖关系除了blog-generator之外，可以用思维导图可以表示为如下所示: 不过这个结构似乎也不太合理，适用于目前而言，业务不是特别大，最好采用这种形式表示: 两图比较主要区别在于将blog-common放到blog-...

2018-09-27

588

资源下载

更多资源

腾讯云软件源

为解决软件依赖安装时官方源访问速度慢的问题，腾讯云为一些软件搭建了缓存服务。您可以通过使用腾讯云软件源站来提升依赖包的安装速度。为了方便用户自由搭建服务架构，目前腾讯云软件源站支持公网访问和内网访问。

Nacos

Nacos /nɑ:kəʊs/ 是 Dynamic Naming and Configuration Service 的首字母简称，一个易于构建 AI Agent 应用的动态服务发现、配置管理和AI智能体管理平台。Nacos 致力于帮助您发现、配置和管理微服务及AI智能体应用。Nacos 提供了一组简单易用的特性集，帮助您快速实现动态服务发现、服务配置、服务元数据、流量管理。Nacos 帮助您更敏捷和容易地构建、交付和管理微服务平台。

Spring

Spring框架（Spring Framework）是由Rod Johnson于2002年提出的开源Java企业级应用框架，旨在通过使用JavaBean替代传统EJB实现方式降低企业级编程开发的复杂性。该框架基于简单性、可测试性和松耦合性设计理念，提供核心容器、应用上下文、数据访问集成等模块，支持整合Hibernate、Struts等第三方框架，其适用范围不仅限于服务器端开发，绝大多数Java应用均可从中受益。

Rocky Linux

Rocky Linux（中文名：洛基）是由Gregory Kurtzer于2020年12月发起的企业级Linux发行版，作为CentOS稳定版停止维护后与RHEL（Red Hat Enterprise Linux）完全兼容的开源替代方案，由社区拥有并管理，支持x86_64、aarch64等架构。其通过重新编译RHEL源代码提供长期稳定性，采用模块化包装和SELinux安全架构，默认包含GNOME桌面环境及XFS文件系统，支持十年生命周期更新。

阿里云Api网关导入Swagger功能简介

广告位

1. 什么是swagger

2. Api网关的定位

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

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

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

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

1.3.1 后端服务类型:HTTP

3.3.2 后端服务类型:HTTP-VPC

3.3.3 后端服务类型: MOCK

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

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

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

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

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

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

5.1 ImportSwagger接口使用

请求参数

返回参数

对象说明

5.2 通过Web控制台导入Swagger

6. 总结

Reference

网站选择什么样配置的服务器合适？

SSM框架构建多模块之业务拆分实践

相关文章

发表评论

资源下载

腾讯云软件源

Nacos

Spring

Rocky Linux

欢迎您来访！

阿里云Api网关导入Swagger功能简介

广告位

1. 什么是swagger

2. Api网关的定位

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

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

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

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

1.3.1 后端服务类型:HTTP

3.3.2 后端服务类型:HTTP-VPC

3.3.3 后端服务类型: MOCK

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

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

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

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

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

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

5.1 ImportSwagger接口使用

请求参数

返回参数

对象说明

5.2 通过Web控制台导入Swagger

6. 总结

Reference

网站选择什么样配置的服务器合适？

SSM框架构建多模块之业务拆分实践

相关文章

发表评论

资源下载

腾讯云软件源

Nacos

Spring

Rocky Linux

欢迎您来访！

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