yangliu da8e53011a feat: 添加redis相关配置与依赖		3 months ago
..
src	da8e53011a feat: 添加redis相关配置与依赖	3 months ago
README.md	fa9efc84d4 feat：更新接口文档依赖	3 months ago
pom.xml	fa9efc84d4 feat：更新接口文档依赖	3 months ago

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 中添加如下配置：

lnxx:
  knife4j:
    doc:
      # 基础配置
      enable: false  # 禁用普通模式
      title: "微服务 API 文档聚合"
      description: "统一管理所有微服务的 API 文档"
      version: "1.0.0"
      
      # 网关配置
      gateway:
        enable: true  # 启用网关模式
        services:     # 配置需要聚合的服务列表
          # 用户服务
          - name: "用户服务"
            url: "/v3/api-docs"  # 注意：这里不需要服务名称前缀
            description: "用户注册、登录、权限管理等相关接口"
          
          # 订单服务
          - name: "订单服务"
            url: "/v3/api-docs"  # 注意：这里不需要服务名称前缀
            description: "订单创建、查询、状态管理等相关接口"
          
          # 商品服务
          - name: "商品服务"
            url: "/v3/api-docs"  # 注意：这里不需要服务名称前缀
            description: "商品信息、库存、分类管理等相关接口"
          
          # 支付服务
          - name: "支付服务"
            url: "/v3/api-docs"  # 注意：这里不需要服务名称前缀
            description: "支付处理、退款、对账等相关接口"
          
          # 通知服务
          - name: "通知服务"
            url: "/v3/api-docs"  # 注意：这里不需要服务名称前缀
            description: "短信、邮件、推送通知等相关接口"

2.3 网关路由配置

确保网关能正确路由到各个微服务，关键是要配置 StripPrefix 过滤器：

spring:
  cloud:
    gateway:
      routes:
        # 用户服务路由
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/user-service/**
          filters:
            - StripPrefix=1  # 移除路径前缀，将 /user-service/v3/api-docs 转换为 /v3/api-docs
        
        # 订单服务路由
        - id: order-service
          uri: lb://order-service
          predicates:
            - Path=/order-service/**
          filters:
            - StripPrefix=1  # 移除路径前缀
        
        # 商品服务路由
        - id: product-service
          uri: lb://product-service
          predicates:
            - Path=/product-service/**
          filters:
            - StripPrefix=1  # 移除路径前缀
        
        # 支付服务路由
        - id: payment-service
          uri: lb://payment-service
          predicates:
            - Path=/payment-service/**
          filters:
            - StripPrefix=1  # 移除路径前缀
        
        # 通知服务路由
        - id: notification-service
          uri: lb://notification-service
          predicates:
            - Path=/notification-service/**
          filters:
            - StripPrefix=1  # 移除路径前缀

3. 访问文档

单个服务文档地址：http://服务地址:端口/doc.html
网关聚合文档地址：http://网关地址:端口/swagger-ui/index.html
网关 API 文档：http://网关地址:端口/v3/api-docs/swagger-config

配置说明

微服务配置

配置项	说明	默认值
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
lnxx.knife4j.doc.name	联系方式姓名	-
lnxx.knife4j.doc.url	联系方式网站	-
lnxx.knife4j.doc.email	联系方式邮箱	-

网关配置

配置项	说明	默认值
lnxx.knife4j.doc.gateway.enable	是否启用网关模式	false
lnxx.knife4j.doc.gateway.services	需要聚合的服务列表	-

服务配置参数

配置项	说明	必填
name	服务名称	是
url	服务的 API 文档路径（不需要服务名称前缀）	是
description	服务描述	否

路径配置说明

网关路由工作原理

客户端请求：http://gateway:8080/user-service/v3/api-docs
网关路由：匹配到 user-service 路由
StripPrefix 过滤：移除 /user-service 前缀
转发请求：http://user-service:8081/v3/api-docs

配置示例对比

❌ 错误配置（会导致 404）

# 网关路由配置
spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/user-service/**
          filters:
            - StripPrefix=1

# Swagger 聚合配置
lnxx:
  knife4j:
    doc:
      gateway:
        services:
          - name: "用户服务"
            url: "/user-service/v3/api-docs"  # ❌ 错误：包含服务名称

✅ 正确配置

# 网关路由配置
spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/user-service/**
          filters:
            - StripPrefix=1

# Swagger 聚合配置
lnxx:
  knife4j:
    doc:
      gateway:
        services:
          - name: "用户服务"
            url: "/v3/api-docs"  # ✅ 正确：不包含服务名称

动态配置

如果需要动态配置服务列表，可以：

1. 从注册中心动态获取

@Autowired
private DiscoveryClient discoveryClient;

private List<ServiceUrl> buildServiceUrls() {
    List<ServiceUrl> serviceUrls = new ArrayList<>();
    discoveryClient.getServices().forEach(serviceId -> {
        serviceUrls.add(new ServiceUrl(
            serviceId + "服务",
            "/v3/api-docs",  // 注意：这里不需要服务名称前缀
            serviceId + "相关接口"
        ));
    });
    return serviceUrls;
}

2. 从数据库配置

@Autowired
private ServiceConfigRepository repository;

private List<ServiceUrl> buildServiceUrls() {
    return repository.findAll().stream()
        .map(config -> new ServiceUrl(
            config.getName(),
            "/v3/api-docs",  // 注意：这里不需要服务名称前缀
            config.getDescription()
        ))
        .collect(Collectors.toList());
}

注意事项

网关模式与普通模式不能同时启用
确保网关能正确路由到各个微服务
各个微服务需要单独配置 Knife4j 文档功能
网关中的配置主要用于聚合，不生成自己的 API 文档
服务 URL 路径不需要包含服务名称前缀
网关路由必须配置 StripPrefix 过滤器
建议在生产环境关闭或限制文档访问

常见问题

1. 文档无法访问

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

2. 网关聚合失败（404 错误）

检查微服务的文档地址是否可访问
检查网关路由配置是否正确
检查网络连通性
检查服务列表配置是否正确
检查是否配置了 StripPrefix 过滤器
检查服务 URL 是否包含服务名称前缀

3. 认证失败

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

4. 服务列表为空

检查配置文件中的服务配置是否正确
检查网关模式是否已启用
检查服务 URL 路径是否正确

5. 静态资源无法加载

检查 webjars 依赖是否正确引入
检查资源路径配置是否正确

版本说明

基于 Knife4j 4.x
支持 Spring Boot 2.6.x 及以上版本
支持 Spring Cloud 2021.x 及以上版本
支持 OpenAPI 3 规范

示例项目

完整的配置示例可以参考 application-gateway.yml 文件。

README.md