最近在捣鼓Spring Boot 3.0，虽然每个微服务中的Swagger都配置好了，但要记住每个微服务的IP和端口来访问是有点不方便的。之前在Spring Boot 2.X时候，用过Spring Cloud Gateway中聚合来展示觉得还不错，但是升级之后就报错。看了knife4j的官方文档，发现目前在Spring Cloud Gateway中只支持knife4j的swagger v2版本。

用Spring Cloud Gateway聚合swagger v3不行，那就试下官方介绍的Knife4jAggregationDesktop方式吧！Desktop顾名思义就是桌面版，但是官方不提供jar包，需要用docker来安装。官方也有提供教程，但是看起来有复杂，这里只是针对连接nacos方式的更简单易懂的教程。

一、Docker环境准备

Linux 下可以使用docker或者podman；Windows下可以使用Docker Desktop (之前有写过一篇文章:https://www.jianshu.com/p/d95680ad520a ,关于安装Docker Desktop)。安装过程，这里不多说了，本次使用的Linux下docker。

二、运行容器

使用下面的命令下载docker镜像：

docker pull xiaoymin/knife4j:v2.0

下载完成后，然后新建一个目录用于存放配置文件，我建的目录是：/opt/knife4j，然后运行下面的命令启动容器：

docker run -e knife4j.source=disk -e knife4j.disk.dir="/knife4j/data" -p 10000:10000 -v /opt/knife4j:/knife4j/data --name knife -d xiaoymin/knife4j:v2.0

说明一下，-e knife4j.source=disk，-e knife4j.disk.dir="/knife4j/data" 这两个参数是改写环境变量，将配置信息保存在容器中的/knife4j/data目录下，-v /opt/knife4j:/knife4j/data是将容器中的目录映射到宿主机的目录（前面创建的/opt/knife4j目录），-p 10000:10000这个将容器的端口映射出来，--name knife指定容器的名称。

然后再执行下面的命令查看容器是否运行成功，如果有开启防火墙的话，还要打开宿主机的相关端口：

docker ps -a
#打开防火墙端口，CentOS
firewall-cmd --zone=public --permanent --add-port=10000/tcp
firewall-cmd --reload

然后在你的浏览器中输入 http://【宿主机IP】:10000/doc.html 并回车，看到如下页面即为成功运行。

三、配置聚合

上图看到的只是一个默认的示例文档，想要聚合显示多个微服务的Swagger文档，还需要配置。这里介绍的是通过连接nacos获取微服务的方式聚合，优点就是修改了微服务的IP和端口也不用修改配置文件。

进入宿主机的/opt/knife4j目录，发现多了一个ROOT目录，进入这个ROOT目录，下面有一个default.yml文件，这就是默认的示例配置，可以删除掉这个文件。

在ROOT目录下新建一个nacos.properties文件，注意文件的编码要是UTF-8格式，否则会引起乱码。可以在Windows中建好文件，再复制过去，nacos.properties文件内容如下：

# 配置nacos的IP地址和端口号
knife4j.nacos[0].server=192.168.50.26:8848
# 配置nacos的登录账号和密码
knife4j.nacos[0].username=nacos
knife4j.nacos[0].password=nacos
# 配置微服务所在的命名空间
knife4j.nacos[0].namespace=elwin

# 配置第一个微服务的文档
# 文档中显示的服务名
knife4j.nacos[0].routes[0].name=用户及系统
# nacos中注册的服务名
knife4j.nacos[0].routes[0].serviceName=EzLcp-User
# nacos中服务所以的分组名
knife4j.nacos[0].routes[0].groupName=DEFAULT_GROUP
# 服务openapi接口路径，此处是swagger3版本
knife4j.nacos[0].routes[0].location=/v3/api-docs?group=default

#配置第二个微服务的文档
knife4j.nacos[0].routes[1].name=日志服务
knife4j.nacos[0].routes[1].serviceName=EzLcp-Log
knife4j.nacos[0].routes[1].groupName=DEFAULT_GROUP
knife4j.nacos[0].routes[1].location=/v3/api-docs?group=default
#配置第N个微服务的文档...

将上面的文件复制到宿主机ROOT目录下，不用重启容器，直接刷新浏览器的地址就可以看到聚合后的文档了。如下图：

感觉比在Spring Cloud Gateway中配置聚合还简单些，也不用担心生产环境发布后会暴露接口文档。