hfln-interior-gateway/knife4j-doc-spring-boot-starter

Knife4j Doc Starter 使用说明

基于 Knife4j 4.x + OpenAPI 3 规范的接口文档增强解决方案。

特性

• 基于 OpenAPI 3 规范
• 支持 Spring Cloud Gateway 网关聚合文档
• 支持 JWT 等安全认证配置
• 支持接口分组管理
• 支持中文界面

快速开始

1. 微服务中使用

在需要暴露 API 文档的微服务的 pom.xml 中添加依赖：

<dependency>
    <groupId>cn.hfln.framework</groupId>
    <artifactId>knife4j-doc-spring-boot-starter</artifactId>
    <version>${project.version}</version>
</dependency>

在 application.yml 中添加配置：

lnxx:
  knife4j:
    doc:
      enable: true
      base-package: com.your.package  # 接口所在包路径
      title: 服务名称
      description: 服务描述
      version: ${project.version}
      enable-security: true  # 是否启用安全认证

2. Gateway 网关中使用

2.1 添加依赖

在网关项目的 pom.xml 中添加依赖：

<dependency>
    <groupId>cn.hfln.framework</groupId>
    <artifactId>knife4j-doc-spring-boot-starter</artifactId>
    <version>${project.version}</version>
</dependency>

2.2 网关配置

在网关的 application.yml 中添加如下配置：

spring:
  cloud:
    gateway:
      routes:
        # 文档聚合路由
        - id: knife4j
          uri: http://localhost:${server.port}
          predicates:
            - Path=/v3/api-docs/**
          filters:
            - RewritePath=/v3/api-docs/(?<path>.*), /$\{path}/v3/api-docs

lnxx:
  knife4j:
    doc:
      enable: true
      title: API 文档中心
      description: 微服务接口文档
      version: ${project.version}
      enable-security: true

# 配置需要聚合的微服务文档
springdoc:
  swagger-ui:
    path: /doc.html
  api-docs:
    enabled: true
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: cn.hfln

2.3 创建网关聚合配置类

@Configuration
public class Knife4jGatewayConfig {
    
    @Bean
    public RouterFunction<ServerResponse> apiRouter() {
        return RouterFunctions.route()
            .GET("/v3/api-docs/swagger-config", request ->
                ServerResponse.ok().bodyValue(swaggerConfig()))
            .build();
    }

    private Map<String, Object> swaggerConfig() {
        Map<String, Object> config = new HashMap<>();
        // 配置要聚合的微服务，key 为服务名，value 为文档地址
        Map<String, String> services = new HashMap<>();
        services.put("用户服务", "/user-service/v3/api-docs");
        services.put("订单服务", "/order-service/v3/api-docs");
        // ... 添加更多服务
        
        config.put("urls", services);
        return config;
    }
}

3. 访问文档

• 单个服务文档地址：http://服务地址:端口/doc.html
• 网关聚合文档地址：http://网关地址:端口/doc.html

注意事项

1. 网关聚合时，确保所有微服务的 OpenAPI 文档都已启用
2. 如果启用了安全认证，需要在 Swagger UI 界面配置对应的认证信息
3. 建议在生产环境关闭或限制文档访问
4. 网关层建议配置文档访问的路由限制

常见问题

1. 文档无法访问

   • 检查服务是否正常启动
   • 检查网关路由配置是否正确
   • 检查安全认证配置

2. 网关聚合失败

   • 检查微服务的文档地址是否可访问
   • 检查网关路由配置是否正确
   • 检查网络连通性

3. 认证失败

   • 检查认证配置是否正确
   • 确认 Token 格式是否正确
   • 检查认证服务是否正常

配置说明

配置项	说明	默认值
lnxx.knife4j.doc.enable	是否启用文档	true
lnxx.knife4j.doc.base-package	接口扫描包路径	-
lnxx.knife4j.doc.title	文档标题	API 文档
lnxx.knife4j.doc.description	文档描述	-
lnxx.knife4j.doc.version	文档版本	1.0.0
lnxx.knife4j.doc.enable-security	是否启用安全认证	false

版本说明

• 基于 Knife4j 4.x
• 支持 Spring Boot 2.6.x 及以上版本
• 支持 Spring Cloud 2021.x 及以上版本