# 枚举键名生成快速参考

## 三种生成方式

### 🥇 方式 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