swagger_generator_flutter/QUICK_REFERENCE.md

Augment 代码生成快速参考

🚀 快速开始

生成 API 代码

# 生成所有代码
dart run bin/main.dart generate --api --models --split-by-tags

# 只生成 API 接口
dart run bin/main.dart generate --api --split-by-tags

# 只生成数据模型
dart run bin/main.dart generate --models

项目集成

# pubspec.yaml
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

# 运行代码生成
dart pub get
dart pub run build_runner build

---

📋 常见问题解决

Q: 生成的类型不存在怎么办？

// ❌ 错误：生成了不存在的类型
Future<BaseResult<TaskInfoResult>> someMethod();

// ✅ 解决：检查 swagger.json 中是否定义了 TaskInfoResult
// 如果没有定义，联系后端添加 schema 定义
// 或者使用通用类型：
Future<BaseResult<Map<String, dynamic>>> someMethod();

Q: 接口缺少参数怎么办？

// ❌ 错误：swagger 中没有定义参数，但生成器添加了
@POST('/api/v1/SomeAction')
Future<BaseResult<void>> someAction(
  @Body() Map<String, dynamic> request  // 不应该存在
);

// ✅ 解决：检查 swagger.json 中的参数定义
// 如果确实需要参数，联系后端在 swagger 中添加定义

Q: 可空性不正确怎么办？

// ❌ 错误：字段应该可空但生成为非空
final String name;  // 但实际可能为 null

// ✅ 解决：检查 swagger.json 中的 nullable 字段
{
  "name": {
    "type": "string",
    "nullable": true  // 添加这个字段
  }
}

Q: 分页接口没有使用 BasePageResult？

// ❌ 错误：分页接口使用了错误的返回类型
Future<BaseResult<List<UserResult>>> getUserList();

// ✅ 解决：检查接口是否真的是分页接口
// 确保 swagger 中定义了分页相关的查询参数和响应结构
Future<BasePageResult<UserResult>> getUserList();

---

🔧 调试技巧

1. 检查 swagger.json

# 验证 swagger.json 格式
curl -X POST "https://validator.swagger.io/validator/debug" \
  -H "Content-Type: application/json" \
  -d @swagger.json

2. 查看生成日志

# 启用详细日志
dart run bin/main.dart generate --api --models --verbose

3. 手动验证类型

// 在生成的代码中添加断言验证
assert(response.data is UserResult);
assert(response.data?.name != null);

---

📝 代码模板

标准 API 接口模板

/// {接口描述}
@{HTTP_METHOD}('{路径}')
Future<{返回类型}> {方法名}(
  // 路径参数（如果有）
  @Path('{参数名}') {类型} 参数名,
  
  // 查询参数（如果有）
  @Query('{参数名}') {类型}? 参数名,
  
  // 请求体（仅当 swagger 中明确定义时）
  @Body() {类型} request
);

标准数据模型模板

@JsonSerializable(checked: true, includeIfNull: false)
class {类名} {
  /// {字段描述}
  final {类型} {字段名};
  
  const {类名}({
    required this.{非空字段},
    this.{可空字段},
  });

  factory {类名}.fromJson(Map<String, dynamic> json) =>
      _${类名}FromJson(json);

  Map<String, dynamic> toJson() => _${类名}ToJson(this);
}

---

⚡ 性能优化

1. 按需导入

// ✅ 只导入需要的类型
import 'package:learning_officer_oa/common/models/common/base_result.dart';

// ❌ 避免导入不需要的类型
// import 'package:learning_officer_oa/common/models/common/base_page_result.dart';

2. 使用 const 构造函数

// ✅ 使用 const 构造函数
const UserResult({
  required this.id,
  required this.name,
});

// ❌ 避免非 const 构造函数
UserResult({
  required this.id,
  required this.name,
});

3. 合理的类型选择

// ✅ 使用具体类型
Future<BaseResult<UserResult>> getUser();

// ❌ 避免过度使用 dynamic
Future<BaseResult<dynamic>> getUser();

---

🛡️ 安全检查

生成前检查

• swagger.json 格式正确
• 所有 $ref 引用存在
• 版本信息匹配

生成后检查

• 代码通过 dart analyze
• 所有导入都存在
• 类型定义完整
• 可空性正确

部署前检查

• 运行所有测试
• 代码格式化
• 文档更新
• 版本标记

---

📞 获取帮助

常见错误代码

• E001: swagger.json 格式错误
• E002: 缺少必要的 schema 定义
• E003: $ref 引用不存在
• E004: 类型映射失败

联系方式

• 技术支持: 联系后端团队完善 swagger 文档
• Bug 报告: 提交到项目 Issues
• 功能请求: 通过 PR 贡献代码

---

快速参考版本: v2.0
最后更新: 2025-01-24