# Knife4j Doc Starter 使用说明

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

## 特性

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

## 快速开始

### 1. 微服务中使用

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

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

在 `application.yml` 中添加配置：

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

### 2. Gateway 网关中使用

#### 2.1 添加依赖

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

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

#### 2.2 网关配置

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

```yaml
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 过滤器**：

```yaml
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 | 服务描述 | 否 |

## 路径配置说明

### 网关路由工作原理

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

### 配置示例对比

#### ❌ 错误配置（会导致 404）
```yaml
# 网关路由配置
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"  # ❌ 错误：包含服务名称
```

#### ✅ 正确配置
```yaml
# 网关路由配置
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. 从注册中心动态获取

```java
@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. 从数据库配置

```java
@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());
}
```

## 注意事项

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

## 常见问题

### 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` 文件。