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

最新推荐文章于 2023-11-13 14:58:13 发布
最新推荐文章于 2023-11-13 14:58:13 发布
阅读量1.2k 收藏 1
点赞数
文章标签： 后端 json
原文链接：https://yq.aliyun.com/articles/645874
版权
广告位

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的后端类型用于直接配置后端服务地址，一般用于后端地址可以直接访问的场合。

属性说明:

属性名称类型描述
typestring必填；值为HTTP
addressstring必填；用于标识后端服务地址
pathstring必填:用于标识后端服务路径。支持路径变量
methodstring必填：后端请求方法
timeoutint选填，默认为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授权名导入。

属性说明:

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

示例:

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

3.3.3 后端服务类型: MOCK

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

属性说明:

属性名称类型描述
typestring必填；值为:MOCK
mockResultstring必填；mock返回结果
mockStatusCodeInteger选填
mockHeadersHeader选填

Header 的 说明

属性名称类型描述
namestring必填
valuestring必填

示例:

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

属性说明:

属性名称类型描述
backendNamestring必填；后端参数名称
valuestring必填；常量值
locationString必填；常量参数存放位置，可选值:[query,header]
descriptionstring可选；用于对该常量进行说明

示例:

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

属性说明:

属性名称类型描述
systemNamestring必填；系统参数名称
backendNamestring必填；后端参数名称
locationString必填；常量参数存放位置，可选值:[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：

请求参数

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

返回参数

名称数据类型描述
RequestIdString本次请求编号
SuccessApiImportSwaggerSuccess本次所有通过swagger导入成功的API信息
FailedApiImportSwaggerFailed本次所有通过swagger导入失败的API信息

对象说明

ApiImportSwaggerSuccess

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

ApiImportSwaggerFailed

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

5.2 通过Web控制台导入Swagger

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

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

6. 总结

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

Reference

weixin_34279184
关注
SpringBoot2.0与微服务实践系列教程（本专栏导航）
Nicky's blog
04-10 6447
本专栏基于Springboot2.0，配套自己写的代码例子和图例。内容涉及从基础入门到微服务架构的实践，包括基础的配置用法，web，数据库，Redis，日志使用，也涉及到企业级开发的消息队列，Mongodb，ElasticSearch、OAuth2.0、JWT、还有微服务系列Spring Cloud、Dubbo、Spring Cloud Aliaba，形成一个体系的博客，并有源码的简单分析，适合作为入门的教程 ......
Java 学习路线大全，再也不用迷路啦（持续更新）
腾讯全栈-ITCJF
10-14 2810
路线特点 最新，完整一条龙，从入门到入土（⭐ 表示推荐学习） 给出目标、学习建议、关键知识点、最优资源以及各类资源推荐（视频、书籍、文档、项目、工具等） 划分阶段、更有计划，且在最后给出持续学习的方向、探索 Java 程序员发展的无限可能 前言 首先呢，我们要了解 Java 的应用场景和就业方向，看看和自己的学习目的是否一致，目前，Java 的岗位需求多，是后台开发的主流编程语言，功能强大，还是很值得学习的。 阶段 1：Java 入门 目标 培养兴趣、快速上手 前期准备 准备好一款在线、随时随地
aws-apigateway-importer, 使用Amazon网关，Swagger和RAML的工具.zip
09-18
aws-apigateway-importer, 使用Amazon网关，Swagger和RAML的工具 网关导入程序Amazon API网关导入器允许你从Swagger或者 RAML API表示create创建或者更新网关 API APIs 。要了解更多关于API网关，请参见文档文档或者 API文档文档。 更新在 API，swag
淘东电商项目（05） - Swagger及网关统一管理API
阿甘兄
02-10 5188
引言 在上一节《淘东电商项目（04） - 注册中心及Feign远程调用》主要讲解了注册中心以及使用Feign远程调用。 代码已提交至Github（版本号：``），有兴趣的同学可以下载来看看： https://github.com/ylw-github/taodong-shop 本文将开始讲解使用Swagger管理每个微服务的API，并使用网关来进行统一管理。 本文目录结构： l____引言 l...
AWS API Gateway Swagger定义
weixin_30561425的博客
03-13 489
导出Swagger接口定义文件 在AWS API Gateway界面上，可以导出swagger接口定义文件。 而后利用Node js swagger-ui 依赖，生成swagger接口地址 CloudFormation模版配置API Gateway参数 对于RequestBody配置方式 例：给该method配置RequestModels MethodPostForUpdate...
《果然新鲜》电商项目（05）- Swagger及网关统一管理API
专业的计算机毕业设计指南
12-28 426
该项目是采用目前比较流行的`SpringBoot`/`SpringCloud`构建微服务电商项目，项目叫 **《果然新鲜》**，实现一套串联的微服务电商项目，能完全掌握该知识，可以在一线城市拿到月薪25+k薪资。 完全符合一线城市微服务电商的需求，对中国程序猿学习微服务电商架构，有非常大的帮助，该项目涵盖从微服务电商需求讨论、数据库设计、技术选型、互联网安全架构、整合`SpringCloud`各自组件、分布式基础设施、使`Docker+k8s+jenkins`实现微服务自动化部署、项目上线域名配置
Swagger在网关管理所有微服务接口文档配置
xulong5000的专栏
06-05 2883
一：之前一篇文章里面说过如何配置swagger管理接口文档。但是如果开发微服务，那么是不是就需要在每一个微服务里面都去注入swagger？ 那后面服务如果有几十个，上百个，是不是就需要100个swagger地址? 这个做法肯定是不可取的，服务少还行，一旦多了，就会添加开发成本，维护成本。 那么是不是可以在网关统一管理？答应是肯定的。 先不说如何配置，直接上图看效果。这里我配置了2个微服务，在不同的站点下，可以看到，右上角这里的下拉框就出现了2个选项。用户api文档，跟商品api文档。那么今后开发人员需要
前后端分离项目知识汇总（阿里云Oss，EasyExcel，视频点播，SpringCloud，Redis，Nuxt）
m0_67402235的博客
06-21 990
全栈开发流程以下是response对象的属性和方法所以说，response就是代表接口返回的数据在看我们后端定义的接口这样功能就实现了补充下分页条实现方式分页条因为我分页条和表单在同一页面，所以写在同一组件下因为我分页条和表单在同一页面，所以写在同一组件下主要是js对象和java对象的问题，注意区分即可其余的也是直接用element-ui组件直接拿过来改改数据有了查询对象之后把查询对象传入我们写的获取讲师列表即可我们在查询按钮绑定方法测试3、定义增加API4、引入js，写vue页面5、测试6、补充增加和修改
国内常见的14款低代码平台介绍
热门推荐
IT技术分享社区
10-11 6万+
今天给大家分享国内常见的14款低代码平台，欢迎收藏！
SpringCloudAlibaba云商城架构设计
m0_67698950的博客
07-03 383
  云商城采用了当前主流的微服务技术架构，微服务技术栈采用了当前主流的SpringCloud Alibaba技术栈，从接入层、网关层、服务层、数据同步、服务治理、数据处理、第三方接口多个方面进行了精心设计，技术经过了多次挑选、优中选优，最终打造了一套全网最优质的的微服务商城架构体系，解决了大型微服务电商应用中绝大多数难点、痛点问题。  我们过去开发一套系统，前端、后端都需要协同工作，很多时候分工不明确、责任不清晰，沟通成本大幅增加。为了提升开发效率、降低沟通成本，前后端分离的模式应运而生，前后端分离的开发模
前阿里高级码农:深入浅出SpringBoot专题——多环境配置及swagger
weixin_52362480的博客
11-13 164
多环境配置分析 在实际开发中，我们可能会涉及到一些环境，比如local(本地开发环境)，dev(部署到远程的开发环境)，test(预发布环境)，product(生产环境)。显然，不同的环境下，对应不同的配置信息，比如db/redis/mq等，甚至不同的环境下，程序需要做不同的处理。那么springboot项目是如何支持多环境配置的呢? 首先来说，springboot就是一个可执行程序，通过java -jar的方式启动的，那么我们需要在启动的时候，告诉springboot当前的profile(环境)是什么，即
Swagger整合Gateway网关
Dreamer.
03-06 5743
1.添加maven依赖 <dependencies> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-gateway</arti...
网络安全-安全Web网关（SWG）详解
最新发布
wangtd的博客
11-13 3177
安全Web网关（SWG）虽然主要工作在OSI模型的第七层（应用层），但它的监控和控制能力并不仅限于处理通过浏览器的流量。SWG的设计允许它处理和监控所有经过网关的基于HTTP/HTTPS的流量，不论这些流量是通过浏览器、应用程序还是其他任何形式的网络通信产生的。通过这些核心技术，SWG为企业网络环境提供了全面的安全防护，不仅防止了恶意软件的侵入和数据的泄露，还提高了整体网络的安全性和合规性。随着网络威胁的不断演变，SWG的技术也在不断发展，以适应新的安全挑战。
springcloud gateway集成swagger3实现API统一入口
weixin_40954354的博客
11-04 1226
项目使用springcloud gateway作为网关，统一路由各个服务的请求。产品为微服务架构，每一个web controller聚合服务都需要暴露接口给前端（VUE组件实现swagger自动配置API出入参和类型）。在云原生背景下，暴露每个web聚合服务的路由运维成本高且使用不方便。因此使用网关作为open api入口，实现每个聚合服务的接入、访问和debug.
gateway 集成 swagger 的详细教程
凉快
06-04 1万+
pom gateway项目的依赖 本着依赖整洁的原则，我加的是这些： <!--swagger--> <dependency> <groupId>com.spring4all</groupId> <artifactId>swagger-spring-boot-starter</artifactId> <version>1.9.1.RELEASE</version> </de
Spring Cloud Gateway整合Swagger聚合微服务系统API文档(非Zuul)
我的小地方
07-18 4万+
【源码中的Spring Boot版本为2.1.3，更新了一点小细节，主要是看思路吧】最近在学习SpringBoot2和Spring Cloud.Finchley版，网上资料也是少的可怜，大部分还是通过一些github或者码云上的一些开源框架来学习，途中出现的一些bug也只能自己看看源码尝试解决。最近使用Spring Cloud Gateway替换Zuul的时候发现Swagger并不支持以WebF...
Spring Cloud基于zuul 实现API网关并整合swagger
linyuanci的博客
12-09 1033
创建示例服务A和B pom.xml &amp;amp;amp;lt;?xml version=&amp;amp;quot;1.0&amp;amp;quot; encoding=&amp;amp;quot;UTF-8&amp;amp;quot;?&amp;amp;amp;gt; &amp;amp;amp;lt;project xmlns=&amp;amp;quot;http://maven.apache.org/POM/4.0.0&amp
微服网关(Zuul)集成swagger统一模块API文档(2019.12.02)
志豪的博客
12-02 782
微服网关集成swagger统一API文档(使用swagger-bootstrap-ui界面) 使用swagger-bootstrap-ui 好处在于可以使用全局参数,例如请求头,或者公共请求参数。 测试模块改造: (例如当他是商城后台管理模块) 1. 加上swagger依赖: <!--springfox-swagger2依赖--> <dependency>...
15-网关实战：微服务集成Swagger实现在线API文档
码猿技术专栏
03-20 675
上节介绍了网关层面聚合API文档，通过网关的路由信息找到了各个服务的请求地址，这节讲一下微服务如何集成Swagger。 网关的API文档默认调用的是微服务的**/v2/api-docs**这个接口获取API详细信息，比如文章服务的URL：http://localhost:9000/blog-article/v2/api-docs，返回信息如下： 木谷博客系统将swagger这个公共的部分抽离出了一个blog-swagger-starter，这样每个微服务只需要依赖这个starter即能接入swagger。
swagger 生成api 测试 导入excel 注解
06-10
Swagger 本身不支持导入 Excel 来测试 API，但可以通过使用 Swagger 提供的注解和第三方库来实现。 1. Swagger 注解 Swagger 提供了一些注解，可以用来描述 API 信息，包括参数、返回值、请求方法等。其中，比较...
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值