123 lines
2.8 KiB
Markdown
123 lines
2.8 KiB
Markdown
# 枚举键名生成快速参考
|
||
|
||
## 三种生成方式
|
||
|
||
### 🥇 方式 1: Swagger 扩展字段（推荐）
|
||
|
||
**适用场景**: 后端支持 OpenAPI 扩展
|
||
|
||
```json
|
||
{
|
||
"SysTaskTypeEnums": {
|
||
"enum": [1, 2, 3],
|
||
"type": "integer",
|
||
"x-enum-varnames": ["SPOT_CHECK", "CULTURAL", "CLASS_CADRE_MEETING"],
|
||
"x-enum-descriptions": ["抽查", "文创建设", "班干部会议"]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 🥈 方式 2: 配置文件映射（备选）
|
||
|
||
**适用场景**: 后端不支持扩展字段，或需要覆盖 Swagger 定义
|
||
|
||
```yaml
|
||
# generator_config.yaml
|
||
generation:
|
||
models:
|
||
enum_key_mappings:
|
||
SysTaskTypeEnums:
|
||
- value: 1
|
||
name: SPOT_CHECK
|
||
description: 抽查
|
||
- value: 2
|
||
name: CULTURAL
|
||
description: 文创建设
|
||
```
|
||
|
||
### 🥉 方式 3: 智能生成（默认）
|
||
|
||
**适用场景**: 快速原型，临时使用
|
||
|
||
```dart
|
||
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: 生成代码
|
||
|
||
```bash
|
||
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`
|
||
|
||
## 详细文档
|
||
|
||
- 📖 [提案文档](./ENUM_KEY_NAMES_PROPOSAL.md)
|
||
- 📚 [使用指南](./ENUM_KEY_NAMES_USAGE.md)
|
||
- 📝 [实现总结](./ENUM_CONFIG_MAPPING_SUMMARY.md)
|
||
|
||
---
|
||
|
||
**更新日期**: 2025-11-24
|
||
**版本**: v2.0
|
||
|