wangyang

swagger_generator_flutter

Fork 0

7.4 KiB

Raw Permalink Blame History

Swagger Generator Flutter - 示例应用

这是一个完整的示例应用，展示如何在 Flutter 项目中使用 swagger_generator_flutter 作为 dev_dependencies 来生成 API 代码。

📋 项目说明

本示例应用使用 Petstore API 作为演示，展示完整的代码生成流程。

🚀 快速开始

1. 安装依赖

# 使用 flutter 命令
flutter pub get

# 或使用 Makefile
make install

2. 生成 API 代码

方式 1: 使用脚本（推荐）

macOS/Linux:

chmod +x generate_api.sh
./generate_api.sh

Windows:

generate_api.bat

方式 2: 使用 Makefile

# 生成并构建
make build

# 或分步执行
make generate  # 生成 API 代码
make build     # 运行 build_runner

方式 3: 手动执行命令

# 1. 生成 API 代码
dart run swagger_generator_flutter generate --all

# 2. 生成序列化代码
dart run build_runner build --delete-conflicting-outputs

# 3. 格式化代码
dart format lib/generated

3. 运行应用

# 使用 flutter 命令
flutter run

# 或使用 Makefile
make run

📁 项目结构

example_app/
├── lib/
│   ├── common/                      # 公共类
│   │   ├── api_response.dart       # 通用响应包装
│   │   └── paged_response.dart     # 分页响应包装
│   ├── generated/                   # 生成的代码（自动生成）
│   │   ├── api/
│   │   │   ├── v1/
│   │   │   │   ├── pet_api.dart
│   │   │   │   ├── store_api.dart
│   │   │   │   ├── user_api.dart
│   │   │   │   └── index.dart
│   │   │   └── api_client.dart
│   │   ├── api_models/
│   │   │   ├── request/
│   │   │   ├── result/
│   │   │   ├── parameters/
│   │   │   ├── enums/
│   │   │   └── index.dart
│   │   ├── api_paths.dart
│   │   ├── api_documentation.md
│   │   └── SUMMARY.md
│   └── main.dart                    # 应用入口
├── generator_config.yaml            # 代码生成器配置
├── pubspec.yaml                     # 项目依赖配置
├── generate_api.sh                  # 生成脚本（macOS/Linux）
├── generate_api.bat                 # 生成脚本（Windows）
├── Makefile                         # Make 命令配置
└── README.md                        # 本文件

🔧 配置说明

pubspec.yaml

dev_dependencies:
  # 使用相对路径引用（示例）
  swagger_generator_flutter:
    path: ../../
  
  # 实际项目中使用 git 引用
  # swagger_generator_flutter:
  #   git:
  #     url: https://github.com/your-org/swagger_generator_flutter.git
  #     ref: main

generator_config.yaml

主要配置项：

input.swagger_url: Swagger 文档 URL
output.base_dir: 代码输出目录
generation.api.base_result_type: 基础响应类型
generation.models.use_json_serializable: 使用 JSON 序列化

完整配置请参考项目中的 generator_config.yaml 文件。

💻 使用生成的 API

1. 创建 API 客户端

import 'package:dio/dio.dart';
import 'generated/api/api_client.dart';

final dio = Dio(BaseOptions(
  baseUrl: 'https://petstore3.swagger.io/api/v3',
  connectTimeout: const Duration(seconds: 30),
));

final apiClient = ApiClient(dio);

2. 调用 API

// 获取宠物信息
final petApi = apiClient.petApi;
final response = await petApi.getPetById(petId: 1);

if (response.isSuccess) {
  print('Pet: ${response.data}');
}

// 获取用户信息
final userApi = apiClient.userApi;
final user = await userApi.getUserByName(username: 'john');

3. 使用生成的模型

import 'generated/api_models/index.dart';

// 创建请求对象
final createPetRequest = CreatePetRequest(
  name: 'Fluffy',
  category: 'Cat',
  status: PetStatus.available,
);

// 调用 API
final response = await petApi.createPet(request: createPetRequest);

🛠️ Makefile 命令

本项目提供了便捷的 Makefile 命令：

命令	说明
`make help`	显示帮助信息
`make install`	安装依赖
`make generate`	生成 API 代码
`make build`	生成并构建（包含 build_runner）
`make watch`	监听模式（自动重新构建）
`make clean`	清理生成的文件
`make regenerate`	清理并重新生成
`make run`	运行应用
`make test`	运行测试
`make analyze`	分析代码
`make format`	格式化代码
`make check`	完整代码质量检查

🔄 工作流程

开发流程

修改 generator_config.yaml 配置（如果需要）
运行 make build 生成代码
在代码中使用生成的 API
运行 make run 测试应用

更新 API 流程

后端更新 Swagger 文档
运行 make regenerate 重新生成代码
检查生成的代码变更
更新使用 API 的代码（如有破坏性变更）
运行测试确保一切正常

📝 最佳实践

1. 版本控制

选项 A: 忽略生成的代码（推荐用于团队协作）

在 .gitignore 中添加：

lib/generated/

优点：

避免合并冲突
保持仓库清洁
团队成员各自生成

缺点：

需要额外的构建步骤
CI/CD 需要生成代码

选项 B: 提交生成的代码

优点：

克隆即可运行
CI/CD 更简单
明确的代码变更记录

缺点：

可能产生大量代码变更
合并冲突风险

2. 基础类型定义

确保项目中已定义好基础响应类型：

ApiResponse<T>: 通用响应包装
PagedResponse<T>: 分页响应包装

这些类型需要在生成代码前存在。

3. 配置管理

为不同环境创建不同的配置文件：

generator_config.yaml          # 默认配置
generator_config.dev.yaml      # 开发环境
generator_config.staging.yaml  # 测试环境
generator_config.prod.yaml     # 生产环境

4. CI/CD 集成

在 CI/CD 流程中添加代码生成步骤：

# .github/workflows/build.yml
- name: Generate API code
  run: |
    dart run swagger_generator_flutter generate --all
    dart run build_runner build --delete-conflicting-outputs    

- name: Check for uncommitted changes
  run: |
    git diff --exit-code || (echo "Generated code has changes" && exit 1)

🐛 故障排除

问题 1: 找不到命令

Error: Could not find package swagger_generator_flutter

解决:

flutter pub get

问题 2: build_runner 失败

Error: A value of type 'Null' can't be returned from the method 'fromJson'

解决: 检查 api_response.dart 和 paged_response.dart 是否正确生成了 .g.dart 文件。

问题 3: 导入错误

Error: Not found: 'package:example_app/generated/api/api_client.dart'

解决: 确保已运行代码生成命令并且没有错误。

📚 相关资源

📧 获取帮助

如果遇到问题：

查看故障排除部分
查看完整文档
提交 Issue
查看示例代码

📄 许可证

本示例应用仅用于演示目的。

7.4 KiB Raw Permalink Blame History Unescape Escape