2.8 KiB
2.8 KiB
枚举键名生成快速参考
三种生成方式
🥇 方式 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