swagger_generator_flutter/FILE_HEADER_CONFIGURATION.md

# ✅ 文件头注释配置功能

## 📋 功能说明

已添加文件头注释的配置支持，可以通过 `generator_config.yaml` 自定义生成的文件头格式。

**实现日期**: 2025-11-05  
**状态**: ✅ 已完成

---

## 🎯 功能特性

### 1. 配置文件头模板

在 `generator_config.yaml` 中的 `templates.file_header` 配置项可以自定义文件头格式：

```yaml
# 模板配置
templates:
  # 文件头模板
  file_header: |
    // {fileType}
    // 基于 Swagger API 文档: {swaggerUrl}
    // 由 {generatorName} by {author} 生成
    // {copyright}    
```

### 2. 支持的模板变量

| 变量 | 说明 | 示例 |
|------|------|------|
| `{fileName}` | 文件名（完整文件名） | `user_api.dart` |
| `{fileType}` | 文件类型描述 | `API 接口定义`、`模型定义` |
| `{swaggerUrl}` | Swagger 文档 URL | `https://api.example.com/swagger.json` |
| `{generatorName}` | 生成器名称 | `xy_swagger_generator` |
| `{author}` | 作者信息 | `max` |
| `{copyright}` | 版权信息 | `Copyright (C) 2025 YuanXuan. All rights reserved.` |

### 3. 生成器信息配置

生成器信息可以从 `generator` 配置项中读取：

```yaml
generator:
  name: "my_custom_generator"      # 生成器名称
  version: "1.0"                    # 版本号
  author: "Your Name"               # 作者
  copyright: "Copyright (C) 2025 Your Company. All rights reserved."  # 版权信息
```

---

## 📝 配置示例

### 示例 1: 默认模板（不配置时使用）

如果不配置 `templates.file_header`，会使用默认模板：

```dart
// HealthCheck API 接口定义
// 基于 Swagger API 文档: https://api.example.com/swagger.json
// 由 xy_swagger_generator by max 生成
// Copyright (C) 2025 YuanXuan. All rights reserved.
```

### 示例 2: 自定义模板（包含文件名）

```yaml
templates:
  file_header: |
    // {fileName} - {fileType}
    // 基于 Swagger API 文档: {swaggerUrl}
    // 由 {generatorName} by {author} 生成
    // {copyright}    
```

**生成结果**:
```dart
// health_check_api.dart - HealthCheck API 接口定义
// 基于 Swagger API 文档: https://api.example.com/swagger.json
// 由 xy_swagger_generator by max 生成
// Copyright (C) 2025 YuanXuan. All rights reserved.
```

### 示例 3: 简洁模板

```yaml
templates:
  file_header: |
    // {fileType}
    // Generated by {generatorName}
    // {copyright}    
```

**生成结果**:
```dart
// HealthCheck API 接口定义
// Generated by xy_swagger_generator
// Copyright (C) 2025 YuanXuan. All rights reserved.
```

### 示例 4: 多行模板（添加空行）

```yaml
templates:
  file_header: |
    // {fileType}
    // 
    // 基于 Swagger API 文档: {swaggerUrl}
    // 由 {generatorName} by {author} 生成
    // {copyright}    
```

**生成结果**:
```dart
// HealthCheck API 接口定义
// 
// 基于 Swagger API 文档: https://api.example.com/swagger.json
// 由 xy_swagger_generator by max 生成
// Copyright (C) 2025 YuanXuan. All rights reserved.
```

### 示例 5: 公司规范模板

```yaml
generator:
  name: "company_api_generator"
  author: "Dev Team"
  copyright: "Copyright (C) 2025 Company Inc. All rights reserved."

templates:
  file_header: |
    /**
     * {fileType}
     * 
     * @file {fileName}
     * @generated {generatorName} by {author}
     * @source {swaggerUrl}
     * @copyright {copyright}
     */    
```

**生成结果**:
```dart
/**
 * HealthCheck API 接口定义
 * 
 * @file health_check_api.dart
 * @generated company_api_generator by Dev Team
 * @source https://api.example.com/swagger.json
 * @copyright Copyright (C) 2025 Company Inc. All rights reserved.
 */
```

---

## 🔍 实现细节

### 1. 配置读取流程

1. **读取模板**: 从 `templates.file_header` 读取模板字符串
2. **读取生成器信息**: 从 `generator` 配置项读取 `name`、`author`、`copyright`
3. **变量替换**: 使用实际值替换模板中的变量
4. **生成文件头**: 将替换后的模板作为文件头

### 2. 默认值处理

如果配置项不存在，使用默认值：

- `generator.name`: `'xy_swagger_generator'`
- `generator.author`: `'max'`
- `generator.copyright`: `'Copyright (C) 2025 YuanXuan. All rights reserved.'`
- `templates.file_header`: 使用默认模板格式

### 3. 文件类型说明

不同文件类型会生成不同的描述：

- **API 接口文件**: `{tagName} API 接口定义`
- **模型文件**: `{modelName} 模型定义`
- **参数实体类**: `参数实体类 - {className}`
- **索引文件**: `API 模型导出文件`

---

## ✅ 测试验证

### 测试场景

1. ✅ **默认模板** - 不配置时使用默认模板
2. ✅ **自定义模板** - 配置模板后使用自定义格式
3. ✅ **变量替换** - 所有模板变量正确替换
4. ✅ **生成器信息** - 从配置读取生成器信息
5. ✅ **多种文件类型** - API、模型、参数实体类都使用配置的模板

### 测试命令

```bash
cd example/as_dev_dependency

# 1. 配置自定义模板
# 在 generator_config.yaml 中添加:
# templates:
#   file_header: |
#     // {fileType}
#     // Generated by {generatorName}

# 2. 运行生成
dart run swagger_generator_flutter generate --all

# 3. 检查生成的文件头
head -5 generator/api/v2/follow_manager_api.dart
```

---

## 📊 输出示例

### 使用默认模板

```dart
// HealthCheck API 接口定义
// 基于 Swagger API 文档: https://quanxue-test-api.w.23544.com:8843/swagger/v1/swagger.json
// 由 xy_swagger_generator by max 生成
// Copyright (C) 2025 YuanXuan. All rights reserved.
```

### 使用自定义模板

```dart
// HealthCheck API 接口定义
// 基于 Swagger API 文档: https://quanxue-test-api.w.23544.com:8843/swagger/v1/swagger.json
// 由 example_app_generator by Example Team 生成
// Copyright (C) 2025 Example Company. All rights reserved.
```

---

## ⚠️ 注意事项

### 1. 模板格式

- 模板使用 YAML 的多行字符串格式 (`|`)
- 支持多行注释
- 可以使用 `//` 或 `/* */` 格式

### 2. 变量替换

- 变量名必须使用大括号 `{variableName}`
- 变量名区分大小写
- 未定义的变量会被替换为空字符串

### 3. 兼容性

- 如果不配置 `templates.file_header`，会使用默认模板
- 如果配置的模板格式不正确，会尝试添加默认格式

### 4. 文件类型

- `{fileType}` 会根据文件类型自动设置
- `{fileName}` 需要显式传入（在生成时自动传入）

---

## 💡 最佳实践

### 1. 统一格式

```yaml
# ✅ 推荐：在项目根目录的 generator_config.yaml 中统一配置
templates:
  file_header: |
    // {fileType}
    // Generated by {generatorName}
    // {copyright}    
```

### 2. 包含必要信息

```yaml
# ✅ 推荐：包含文件类型、来源、生成器信息
file_header: |
  // {fileType}
  // Source: {swaggerUrl}
  // Generated by {generatorName} by {author}  
```

### 3. 符合公司规范

```yaml
# ✅ 推荐：符合公司代码规范
generator:
  copyright: "Copyright (C) 2025 Your Company. All rights reserved."

templates:
  file_header: |
    // {fileType}
    // {copyright}    
```

### 4. 简洁明了

```yaml
# ✅ 推荐：简洁但包含关键信息
file_header: |
  // {fileType} - Generated by {generatorName}  
```

---

## ✨ 总结

**已完成**:
- ✅ 添加 `templates.file_header` 配置项支持
- ✅ 实现模板变量替换（`{fileName}`, `{fileType}`, `{swaggerUrl}`, `{generatorName}`, `{author}`, `{copyright}`）
- ✅ 从配置读取生成器信息（`generator.name`, `generator.author`, `generator.copyright`）
- ✅ 支持默认模板（当配置不存在时）
- ✅ 更新所有生成器使用配置的文件头

**功能**:
- ✅ 完全可配置的文件头格式
- ✅ 模板变量支持
- ✅ 自动从配置读取生成器信息
- ✅ 向后兼容（默认模板）

**状态**: ✅ **功能完成，可以使用**

现在可以通过 `generator_config.yaml` 完全自定义生成的文件头格式了！