331 lines
7.4 KiB
Markdown
331 lines
7.4 KiB
Markdown
# Swagger Generator Flutter - 示例应用
|
||
|
||
这是一个完整的示例应用，展示如何在 Flutter 项目中使用 `swagger_generator_flutter` 作为 `dev_dependencies` 来生成 API 代码。
|
||
|
||
## 📋 项目说明
|
||
|
||
本示例应用使用 [Petstore API](https://petstore3.swagger.io) 作为演示，展示完整的代码生成流程。
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
# 使用 flutter 命令
|
||
flutter pub get
|
||
|
||
# 或使用 Makefile
|
||
make install
|
||
```
|
||
|
||
### 2. 生成 API 代码
|
||
|
||
#### 方式 1: 使用脚本（推荐）
|
||
|
||
**macOS/Linux:**
|
||
```bash
|
||
chmod +x generate_api.sh
|
||
./generate_api.sh
|
||
```
|
||
|
||
**Windows:**
|
||
```cmd
|
||
generate_api.bat
|
||
```
|
||
|
||
#### 方式 2: 使用 Makefile
|
||
|
||
```bash
|
||
# 生成并构建
|
||
make build
|
||
|
||
# 或分步执行
|
||
make generate # 生成 API 代码
|
||
make build # 运行 build_runner
|
||
```
|
||
|
||
#### 方式 3: 手动执行命令
|
||
|
||
```bash
|
||
# 1. 生成 API 代码
|
||
dart run swagger_generator_flutter generate --all
|
||
|
||
# 2. 生成序列化代码
|
||
dart run build_runner build --delete-conflicting-outputs
|
||
|
||
# 3. 格式化代码
|
||
dart format lib/generated
|
||
```
|
||
|
||
### 3. 运行应用
|
||
|
||
```bash
|
||
# 使用 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
|
||
|
||
```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 客户端
|
||
|
||
```dart
|
||
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
|
||
|
||
```dart
|
||
// 获取宠物信息
|
||
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. 使用生成的模型
|
||
|
||
```dart
|
||
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` | 完整代码质量检查 |
|
||
|
||
## 🔄 工作流程
|
||
|
||
### 开发流程
|
||
|
||
1. 修改 `generator_config.yaml` 配置（如果需要）
|
||
2. 运行 `make build` 生成代码
|
||
3. 在代码中使用生成的 API
|
||
4. 运行 `make run` 测试应用
|
||
|
||
### 更新 API 流程
|
||
|
||
1. 后端更新 Swagger 文档
|
||
2. 运行 `make regenerate` 重新生成代码
|
||
3. 检查生成的代码变更
|
||
4. 更新使用 API 的代码（如有破坏性变更）
|
||
5. 运行测试确保一切正常
|
||
|
||
## 📝 最佳实践
|
||
|
||
### 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 流程中添加代码生成步骤：
|
||
|
||
```yaml
|
||
# .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
|
||
```
|
||
|
||
**解决**:
|
||
```bash
|
||
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'
|
||
```
|
||
|
||
**解决**: 确保已运行代码生成命令并且没有错误。
|
||
|
||
## 📚 相关资源
|
||
|
||
- [完整使用指南](../../USAGE_AS_DEV_DEPENDENCY.md)
|
||
- [配置文件模板](../../generator_config.template.yaml)
|
||
- [项目主文档](../../README.md)
|
||
- [Petstore API 文档](https://petstore3.swagger.io)
|
||
|
||
## 📧 获取帮助
|
||
|
||
如果遇到问题：
|
||
|
||
1. 查看 [故障排除](#-故障排除) 部分
|
||
2. 查看 [完整文档](../../USAGE_AS_DEV_DEPENDENCY.md)
|
||
3. 提交 Issue
|
||
4. 查看示例代码
|
||
|
||
## 📄 许可证
|
||
|
||
本示例应用仅用于演示目的。
|