wangyang

swagger_generator_flutter

Fork 0

7.8 KiB

Raw Blame History

✅ 文件头注释配置功能

📋 功能说明

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

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

🎯 功能特性

1. 配置文件头模板

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

# 模板配置
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 配置项中读取：

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

📝 配置示例

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

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

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

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

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

生成结果:

// 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: 简洁模板

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

生成结果:

// HealthCheck API 接口定义
// Generated by xy_swagger_generator
// Copyright (C) 2025 YuanXuan. All rights reserved.

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

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

生成结果:

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

示例 5: 公司规范模板

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}
     */

生成结果:

/**
 * 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. 配置读取流程

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

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 模型导出文件

✅ 测试验证

测试场景

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

测试命令

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

📊 输出示例

使用默认模板

// 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.

使用自定义模板

// 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. 统一格式

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

2. 包含必要信息

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

3. 符合公司规范

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

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

4. 简洁明了

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

✨ 总结

已完成:

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

功能:

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

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

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

7.8 KiB Raw Blame History Unescape Escape

✅ 文件头注释配置功能

📋 功能说明

🎯 功能特性

1. 配置文件头模板

2. 支持的模板变量

3. 生成器信息配置

📝 配置示例

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

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

示例 3: 简洁模板

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

示例 5: 公司规范模板

🔍 实现细节

1. 配置读取流程

2. 默认值处理

3. 文件类型说明

✅ 测试验证

测试场景

测试命令

📊 输出示例

使用默认模板

使用自定义模板

⚠️ 注意事项

1. 模板格式

2. 变量替换

3. 兼容性

4. 文件类型

💡 最佳实践

1. 统一格式

2. 包含必要信息

3. 符合公司规范

4. 简洁明了

✨ 总结

7.8 KiB

Raw Blame History