# Swagger 代码生成器配置文件模板
# 复制此文件到您的项目根目录，重命名为 generator_config.yaml，并根据需要修改

# 基本配置
generator:
  name: "my_project_generator"  # 修改为您的项目生成器名称
  version: "1.0"
  author: "Your Name"  # 修改为您的名字
  copyright: "Copyright (C) 2025 Your Company. All rights reserved."  # 修改为您的版权信息

# 输入配置
input:
  # Swagger 文档源配置（支持多版本）
  swagger_urls:
    # 简写形式：直接列出 URL
    - "https://your-api.com/swagger/v1/swagger_v3.json"
    - "https://your-api.com/swagger/v2/swagger_v3.json"
    
    # 完整形式：可以控制每个版本的启用状态
    # - url: "https://your-api.com/swagger/v1/swagger_v3.json"
    #   enabled: true      # 可选，是否启用此版本（默认: true）
  
  # 验证配置
  validate_schema: true
  strict_mode: true

# 输出配置
output:
  # 输出目录（根据您的项目结构修改）
  base_dir: "./lib/generated"
  api_dir: "./lib/generated/api"
  models_dir: "./lib/generated/api_models"
  
  # 文件命名
  api_file_suffix: "_api.dart"
  model_file_suffix: ".dart"
  
  # 是否按 tag 分组
  split_by_tags: true

  # 只生成指定 tags 的 API 和模型（可选）
  # 如果不指定或为空，则生成所有 tags
  # 如果某个 endpoint 有多个 tags，只要其中一个在列表中就会生成
  included_tags:
    # - "User"
    # - "Pet"
    # - "Store"

  # 从代码生成中排除指定的 tags
  # 适用于内部、废弃或不需要的 API
  # 如果一个 endpoint 的所有 tags 都被排除，则该 endpoint 不会生成
  excluded_tags:
    # - "Internal"
    # - "Deprecated"
    # - "Legacy"

  # 跳过的目录列表（这些目录下的文件将不会被生成）
  # 支持相对路径和绝对路径，支持目录名或完整路径
  ignored_directories:
    # - "api/v1"              # 跳过 v1 版本的 API
    # - "api_models/request"  # 跳过请求模型目录
    # - "./lib/generated/api/v2"  # 跳过特定路径
  
  # 跳过的文件名列表（这些文件将不会被生成）
  # 支持精确匹配、通配符匹配和模式匹配
  ignored_files:
    # 精确匹配文件名
    # - "user_api.dart"              # 跳过名为 user_api.dart 的文件
    # - "mobile_manager_api.dart"    # 跳过指定文件
    
    # 通配符匹配（支持前缀和后缀）
    # - "*_api.dart"                 # 跳过所有以 _api.dart 结尾的文件
    # - "user*.dart"                 # 跳过所有以 user 开头的 .dart 文件
    # - "*manager*"                  # 跳过所有包含 manager 的文件名
    
    # 示例：跳过所有 v1 版本的 API 文件
    # - "*_api_v1.dart"
    # - "*V1*.dart"

# 代码生成配置
generation:
  # API 接口配置
  api:
    enabled: true
    use_retrofit: true
    use_dio: true
    parser: "JsonSerializable"

    # API Client 配置
    # 主 API 客户端类的名称和文件名配置
    client:
      class_name: "ApiClient"        # API 客户端类名（默认: ApiClient）
      file_name: "api_client"        # API 客户端文件名（默认: api_client，不含 .dart 后缀）
    
    # 版本提取配置（多版本支持）
    version_extraction:
      # 版本提取正则表达式模式
      # 默认: "/api/v(\\d+)/" 匹配 /api/v1/, /api/v2/ 等
      pattern: "/api/v(\\d+)/"
      
      # 默认版本（当无法从路径提取版本时使用）
      default_version: "v1"
    
    # 基础类型配置（根据您的项目调整）
    # 如果您的项目有统一的响应模型，请在此处配置
    base_result_type: "BaseResult"  # 基础响应模型名称
    base_page_result_type: "BasePageResult" # 分页响应模型名称

    # 基础模型的导入路径（可选）
    # 如果提供了路径，将在 api_models/index.dart 中自动导出
    # 如果留空，则不会生成导出语句
    base_result_import: "" # 例如: "package:your_project/common/models/base_result.dart"
    base_page_result_import: "" # 例如: "package:your_project/common/models/base_page_result.dart"
    
    # 方法命名
    method_naming: "camelCase"  # camelCase, snake_case
    
  # 数据模型配置
  models:
    enabled: true
    use_json_serializable: true
    
    # JsonSerializable 配置
    json_serializable:
      checked: true
      include_if_null: false
      explicit_to_json: true
      
    # 类命名
    class_naming: "PascalCase"  # PascalCase, snake_case
    field_naming: "camelCase"   # camelCase, snake_case
    
    # 构造函数配置
    use_const_constructor: true
    required_for_non_nullable: true
    
    # 枚举键名映射配置（可选）
    # 用于为枚举值定义有意义的键名和描述
    # 优先级：配置文件映射 > x-enum-varnames > 智能生成
    # 
    # 使用场景：
    # 1. 后端不支持 x-enum-varnames 扩展字段
    # 2. 需要覆盖 Swagger 文档中的枚举键名
    # 3. 需要为枚举值添加自定义描述
    # 
    # 格式:
    # enum_key_mappings:
    #   枚举名称:
    #     - value: 枚举值（数字或字符串）
    #       name: 枚举键名（大写下划线命名）
    #       description: 枚举描述（可选）
    # 
    # 示例:
    # enum_key_mappings:
    #   SysTaskTypeEnums:
    #     - value: 1
    #       name: SPOT_CHECK
    #       description: 抽查
    #     - value: 2
    #       name: CULTURAL
    #       description: 文创建设
    #     - value: 3
    #       name: CLASS_CADRE_MEETING
    #       description: 班干部会议
    #   
    #   UserStatus:
    #     - value: "active"
    #       name: ACTIVE
    #       description: 活跃用户
    #     - value: "inactive"
    #       name: INACTIVE
    #       description: 非活跃用户
    #     - value: "banned"
    #       name: BANNED
    #       description: 已封禁
    # 
    enum_key_mappings:
      # 在此处添加您的枚举映射配置
      # SysTaskTypeEnums:
      #   - value: 1
      #     name: SPOT_CHECK
      #     description: 抽查
      #   - value: 2
      #     name: CULTURAL
      #     description: 文创建设

# 类型映射配置
type_mapping:
  # OpenAPI -> Dart 类型映射
  string: "String"
  integer: "int"
  number: "double"
  boolean: "bool"
  array: "List"
  object: "Map<String, dynamic>"
  
  # 特殊类型处理
  date: "DateTime"
  date-time: "DateTime"
  binary: "Uint8List"

# 导入管理配置
imports:
  # 按需导入
  on_demand: true
  
  # 自动排序
  auto_sort: true
  
  # 分组导入
  group_imports: true
  
  # 标准库导入
  dart_imports:
    - "dart:convert"
    - "dart:typed_data"
    
  # 第三方库导入
  package_imports:
    - "package:dio/dio.dart"
    - "package:retrofit/retrofit.dart"
    - "package:json_annotation/json_annotation.dart"

# 验证配置
validation:
  # 严格模式
  strict_mode: true
  
  # 检查项
  checks:
    - "schema_exists"
    - "ref_resolution"
    - "type_consistency"
    - "nullable_correctness"
    - "required_fields"
    
  # 错误处理
  on_error: "warn"  # fail, warn, ignore
  
  # 警告处理
  on_warning: "log"  # fail, log, ignore

# 优化配置
optimization:
  # 代码优化
  remove_unused_imports: true
  optimize_imports: true
  
  # 性能优化
  cache_schemas: true
  parallel_generation: false
  
  # 内存优化
  lazy_loading: true

# 调试配置
debug:
  # 详细日志
  verbose: false
  
  # 调试输出
  debug_output: false
  
  # 性能监控
  performance_monitoring: false
  
  # 生成统计
  generation_stats: true

# 兼容性配置
compatibility:
  # Dart 版本
  dart_version: ">=3.0.0"
  
  # Flutter 版本
  flutter_version: ">=3.10.0"
  
  # 依赖版本
  dependencies:
    dio: "^5.0.0"
    retrofit: "^4.0.0"
    json_annotation: "^4.8.0"
    
  dev_dependencies:
    build_runner: "^2.3.0"
    retrofit_generator: "^8.0.0"
    json_serializable: "^6.6.0"

# 自定义配置
custom:
  # 项目特定配置
  project_name: "your_project"  # 修改为您的项目名称
  
  # 特殊处理规则
  special_handling:
    # 健康检查接口返回 void
    health_check_paths:
      - "/health"
      - "/healthcheck"
      - "/api/health"
      
    # 分页接口参数名
    pagination_params:
      - "page"
      - "size"
      - "limit"
      - "offset"
      - "pageIndex"
      - "pageSize"
      
    # 忽略的路径
    ignored_paths:
      - "/swagger"
      - "/docs"
      
    # 忽略的 tags
    ignored_tags:
      - "Internal"
      - "Debug"

# 模板配置
templates:
  # 文件头模板
  # 支持模板变量:
  #   {fileName} - 文件名（如 "user_api.dart"）
  #   {fileType} - 文件类型描述（如 "API 接口定义"、"模型定义"）
  #   {swaggerUrl} - Swagger 文档 URL
  #   {generatorName} - 生成器名称（从 generator.name 读取）
  #   {author} - 作者（从 generator.author 读取）
  #   {copyright} - 版权信息（从 generator.copyright 读取）
  file_header: |
    // {fileType}
    // 基于 Swagger API 文档: {swaggerUrl}
    // 由 {generatorName} by {author} 生成
    // {copyright}
    
  # API 类模板
  # 支持模板变量:
  #   {tagName} - Tag 名称（如 "User"、"Task"）
  #   {className} - 类名（如 "UserApi"、"TaskApi"）
  api_class: |
    /// {tagName} API 接口
    /// 负责处理 {tagName} 相关的接口
    @RestApi(parser: Parser.JsonSerializable)
    abstract class {className} {
      factory {className}(Dio dio, {String? baseUrl}) = _{className};
    }
    
  # 模型类模板
  # 支持模板变量:
  #   {className} - 类名（如 "User"、"Task"）
  #   {constructorParams} - 构造函数参数列表
  model_class: |
    @JsonSerializable(checked: true, includeIfNull: false)
    class {className} {
      const {className}({constructorParams});
      
      factory {className}.fromJson(Map<String, dynamic> json) =>
          _${className}FromJson(json);
          
      Map<String, dynamic> toJson() => _${className}ToJson(this);
    }