# 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. 查看示例代码

## 📄 许可证

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