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

最新推荐文章于 2024-01-26 20:21:12 发布

weixin_39767124

最新推荐文章于 2024-01-26 20:21:12 发布

阅读量242

点赞数

文章标签：微服务需要聚合工程吗我的swagger上面怎么没有models

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

前置知识

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

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

应用架构

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

具体实现

下面详细介绍下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

接下来我们需要自定义Swagger各个配置的节点，简单来说就是自定义Swagger内部的各个获取数据的接口；

/**
 * 自定义Swagger的各个配置节点
 * Created by macro on 2020/7/9.
 */

比如说swagger-resources这个接口，可用于获取所有微服务的api-docs访问路径，获取信息如下，访问地址：http://localhost:9201/swagger-resources

功能演示

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

在此之前先启动我们的Nacos注册中心，然后依次启动micro-knife4j-user、micro-knife4j-order及micro-knife4j-gateway服务；

从网关访问API文档，访问地址：http://localhost:9201/doc.html

我们通过左上角的切换组件即可切换到对应服务的API文档；

查看API文档，我们可以发现所有接口都已经添加了对应的访问前缀，可以正常访问。

切换回Swagger UI

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

首先我们需要在pom.xml中去除knife4j的相关依赖，主要就是下面两个依赖；

<dependencies>

在pom.xml中添加Swagger相关依赖，并去除原来使用的@EnableKnife4j注解；

<dependencies>

重新启动所有服务，访问网关的API文档路径即可查看：http://localhost:9201/swagger-ui.html

总结

对比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