# 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
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 创建网关聚合配置类

```java
@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 及以上版本