wangyang

2.8 KiB

Raw Blame History

枚举键名生成快速参考

三种生成方式

🥇 方式 1: Swagger 扩展字段（推荐）

适用场景: 后端支持 OpenAPI 扩展

{
  "SysTaskTypeEnums": {
    "enum": [1, 2, 3],
    "type": "integer",
    "x-enum-varnames": ["SPOT_CHECK", "CULTURAL", "CLASS_CADRE_MEETING"],
    "x-enum-descriptions": ["抽查", "文创建设", "班干部会议"]
  }
}

🥈 方式 2: 配置文件映射（备选）

适用场景: 后端不支持扩展字段，或需要覆盖 Swagger 定义

# generator_config.yaml
generation:
  models:
    enum_key_mappings:
      SysTaskTypeEnums:
        - value: 1
          name: SPOT_CHECK
          description: 抽查
        - value: 2
          name: CULTURAL
          description: 文创建设

🥉 方式 3: 智能生成（默认）

适用场景: 快速原型，临时使用

enum SysTaskTypeEnums {
  value1(1),
  value2(2),
  value3(3);
}

优先级规则

配置文件映射 > Swagger 扩展字段 > 智能生成

生成结果对比

方式	枚举键名	注释	维护成本
Swagger 扩展字段	✅ 有意义	✅ 有	🟢 低（后端维护）
配置文件映射	✅ 有意义	✅ 有	🟡 中（前端维护）
智能生成	❌ 通用	❌ 无	🟢 低（无需维护）

快速开始

Step 1: 选择方式

后端支持 → 使用方式 1
后端不支持 → 使用方式 2
快速原型 → 使用方式 3

Step 2: 配置（如果使用方式 1 或 2）

方式 1: 联系后端添加 x-enum-varnames 和 x-enum-descriptions

方式 2: 在 generator_config.yaml 中添加配置

Step 3: 生成代码

dart run swagger_generator_flutter:main generate --all

Step 4: 验证结果

检查生成的枚举文件是否有有意义的键名和注释。

常见问题

Q: 如何覆盖 Swagger 文档中的枚举定义？

A: 在配置文件中添加相同枚举名称的映射，配置文件优先级更高。

Q: 可以只配置部分枚举值吗？

A: 可以。未配置的枚举值会使用 Swagger 扩展字段或智能生成。

Q: 如何确保枚举键名符合规范？

A: 使用大写字母和下划线（UPPER_SNAKE_CASE），避免使用 Dart 关键字。

Q: 配置文件映射支持哪些类型？

A: 支持整数枚举 (integer, number) 和字符串枚举 (string)。

示例文件

Swagger 示例: example/swagger_enum_example.json
配置文件示例: example/enum_config_mapping_example.yaml
完整模板: generator_config.template.yaml

详细文档

更新日期: 2025-11-24
版本: v2.0

2.8 KiB Raw Blame History Unescape Escape