微服务需要聚合工程吗_微服务聚合Swagger文档,这波操作是真的香!

记得我的mall-swarm微服务项目中,没有做API文档聚合,访问每个服务的API文档都需要访问单独的swagger-ui.html页面,既然我们使用了微服务,就应该有统一的API文档入口,最近发现knife4j有这方面的支持,本文将详细介绍其实现,希望对大家有所帮助!

前置知识

我们将采用Nacos作为注册中心,Gateway作为网关,使用knife4j来生成API文档,对这些技术不了解的朋友可以看下下面的文章。

  • Spring Cloud Gateway:新一代API网关服务
  • Spring Cloud Alibaba:Nacos 作为注册中心和配置中心使用
  • 给Swagger换了个新皮肤,瞬间高大上了!

应用架构

我们理想的解决方案应该是这样的,网关作为API文档的统一入口,网关聚合所有微服务的文档,通过在网关进行切换来实现对其他服务API文档的访问。

相关服务划分:

  • micro-knife4j-gateway:网关服务,作为微服务API文档的访问入口,聚合所有API文档,需要引入文档前端UI包;
  • micro-knife4j-user:用户服务,普通API服务,不需要引入文档前端UI包;
  • micro-knife4j-order:订单服务,普通API服务,不需要引入文档前端UI包。

具体实现

下面详细介绍下Spring Cloud Gateway + knife4j 聚合API文档的具体实现,依次搭建用户服务、订单服务和网关服务。

micro-knife4j-user

我们首先来搭建用户服务,一个普通的API服务,很简单,仅需三步即可集成knife4j。

  • pom.xml中添加相关依赖,一个SpringBoot的web功能依赖,knife4j的微服务依赖(不包含API文档的前端UI包);
<dependencies>
  • application.yml这添加相关配置,配置一下Nacos注册中心即可;
server:
  • 添加Swagger相关配置,非常常规的配置,添加@EnableKnife4j注解开启knife4j的增强功能。
/**
 * Swagger API相关配置
 */

micro-knife4j-order

我们接下来搭建订单服务,一个普通的API服务,直接参考上面用户服务的搭建即可。

micro-knife4j-gateway

最后我们搭建网关服务,作为微服务API文档的的统一入口,聚合所有微服务的API文档。

  • pom.xml中添加相关依赖,Gateway相关依赖和knife4j的Starter(包含API文档的前端UI包);
<dependencies>
  • application.yml这添加相关配置,配置一下Nacos注册中心,用户服务和订单服务的路由即可;
server:
  • 在网关上添加Swagger资源配置,用于聚合其他微服务中Swagger的api-docs访问路径;
/**
 * Swagger资源配置
 * Created by macro on 2020/7/9.
 */
  • 什么是Swagger的api-docs访问路径?该路径会返回JSON格式数据,Swagger渲染API文档页面的所有数据就是来源于此,比如我们的用户服务会返回如下信息,访问地址:http://localhost:9201/user-service/v2/api-docs
876c06039eb1c873ab4b17695442302b.png
  • 接下来我们需要自定义Swagger各个配置的节点,简单来说就是自定义Swagger内部的各个获取数据的接口;
/**
 * 自定义Swagger的各个配置节点
 * Created by macro on 2020/7/9.
 */
  • 比如说swagger-resources这个接口,可用于获取所有微服务的api-docs访问路径,获取信息如下,访问地址:http://localhost:9201/swagger-resources
dc329c685d9bad30497b61b997f604f0.png

功能演示

接下来我们来演示下微服务API文档聚合的功能,仅需要访问网关的API文档页面即可,可自行切换到相关服务的API文档。

  • 在此之前先启动我们的Nacos注册中心,然后依次启动micro-knife4j-usermicro-knife4j-ordermicro-knife4j-gateway服务;
fbf23011747cacfb3310728710b7ac8e.png
  • 从网关访问API文档,访问地址:http://localhost:9201/doc.html
96c66bb5c4eb68d140bb51565a19583c.png
  • 我们通过左上角的切换组件即可切换到对应服务的API文档;
73dad411259213559800a3a6d1375498.png
  • 查看API文档,我们可以发现所有接口都已经添加了对应的访问前缀,可以正常访问。
626bde92daf700312278fd1584ac0b32.png

切换回Swagger UI

如果你不想使用knife4j的界面,想用原来的Swagger界面,也是可以支持的,切换方法非常简单,下面我们来讲讲。

  • 首先我们需要在pom.xml中去除knife4j的相关依赖,主要就是下面两个依赖;
<dependencies>
  • pom.xml中添加Swagger相关依赖,并去除原来使用的@EnableKnife4j注解;
<dependencies>
  • 重新启动所有服务,访问网关的API文档路径即可查看:http://localhost:9201/swagger-ui.html
2e588f69b153aa32421214f88aff7fab.png

总结

对比knife4j和原生Swagger的微服务使用,再次证明knife4j是springfox-swagger的增强UI实现,完全遵循了springfox-swagger中的使用方式。

参考资料

官方文档:https://doc.xiaominfo.com/guide/ui-front-gateway.html

项目源码地址

https://github.com/macrozheng/springcloud-learning/tree/master/micro-knife4j

推荐阅读

  • 给Swagger换了个新皮肤,瞬间高大上了!
  • 过来人聊聊经历,为什么不要再学JSP了!
  • SpringBoot 2.3.0 新特性一览,快来跟我实践一波!
  • 给Swagger升级了新版本,没想到居然有这么多坑!
  • fastjson到底做错了什么?为什么会被频繁爆出漏洞?
  • 微服务权限终极解决方案,Spring Cloud Gateway + Oauth2 实现统一认证和鉴权!
  • 听说你的JWT库用起来特别扭,推荐这款贼好用的!
  • 线上项目出BUG没法调试?推荐这款阿里开源的诊断神器!
  • 一个不容错过的Spring Cloud实战项目!
  • 我的Github开源项目,从0到20000 Star!

00fcd486e10f24ea78d13225be05a807.png

欢迎关注,点个在看

  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

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

抵扣说明:

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

余额充值