Spring Cloud Gateway 与 Knife4j 集成实践

注意：写于 2025/1/10，未来时间可能失效，请根据具体情况实践。

在微服务架构中，Gateway 通常承担着路由转发、负载均衡、鉴权等职责，而 Knife4j 是一个集 Swagger2 和 OpenAPI3 为一体的增强解决方案，可以帮助开发者快速聚合使用OpenAPI 规范。

本文参考 Knife4j 文档，进行网关处集成实践。

在实践之前，已经准备好了两个微服务，并且已经使用注解注解。

微服务列表:

• Auth service
• Gateway Service
• System Service

目录结构:

主要在 Gateway 中做修改，不涉及其他目录

增加 Knife4j 依赖:

这里请阅读官方文档，看需要什么依赖

在 maven 依赖文件中增加下面的依赖：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-gateway-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

因为我已经在父依赖中增加管理，所以只需引入

Knife4j 服务发现配置
微服务配置之前已准备好了，使用 Nacos 为服务注册、配置中心。

为了方便，这里我使用的是服务发现模式，因为 Spring Boot 3 只支持 OpenAPI3 规范，所以版本选用 OpenAPI3，总的配置如下：

knife4j:
  gateway:
    enabled: true
    tags-sorter: alpha
    operations-sorter: alpha
    strategy: discover
    discover:
      enabled: true
      version: openapi3

访问页面
启动三个服务，成功后访问 http://localhost:9002/doc.html 就可以看见 Knife4j 的页面了，API 现在已经聚合上了

现在切换到 System 服务的 API 文档页面：

调试 API
调试一下 Auth 服务的 API，可以看见是成功的：

再调试 System 服务 API，也是成功的：

启动时打印 URL
为了方便，我们可以在启动类做一些修改，启动的时候打印 URL，需要的时候直接点击就可以了：

在日志中输出 URL：

@SpringBootApplication
@Slf4j
@EnableDiscoveryClient
publicclass GatewayApplication {
    public static void main(String[] args) {
        ConfigurableApplicationContext run= SpringApplication.run(GatewayApplication.class, args);
        Environment env= run.getEnvironment();
        log.info("""
                                                \s
                         -------------------------------------------------
                             Application is running! Access URLs:
                             Local:    http://localhost:{}
                             Doc:      http://localhost:{}/doc.html
                         -------------------------------------------------
                        \s""",
                env.getProperty("server.port"),
                env.getProperty("server.port")
        );
    }
}

效果如此：