203 lines
4.0 KiB
Markdown
203 lines
4.0 KiB
Markdown
# 🚀 快速开始指南
|
||
|
||
5 分钟快速体验 `swagger_generator_flutter` 作为 dev_dependencies 的使用！
|
||
|
||
## ⚡ 极速开始（3 步）
|
||
|
||
### 第 1 步：安装依赖
|
||
|
||
```bash
|
||
cd example/as_dev_dependency
|
||
flutter pub get
|
||
```
|
||
|
||
### 第 2 步：生成代码
|
||
|
||
**macOS/Linux:**
|
||
```bash
|
||
./generate_api.sh
|
||
```
|
||
|
||
**Windows:**
|
||
```cmd
|
||
generate_api.bat
|
||
```
|
||
|
||
**或使用 Make:**
|
||
```bash
|
||
make build
|
||
```
|
||
|
||
### 第 3 步：运行应用
|
||
|
||
```bash
|
||
flutter run
|
||
# 或
|
||
make run
|
||
```
|
||
|
||
## 📱 体验完整流程
|
||
|
||
1. **查看配置文件**
|
||
```bash
|
||
cat generator_config.yaml
|
||
```
|
||
这是代码生成器的配置，定义了输入源和输出目录。
|
||
|
||
2. **查看生成的代码**
|
||
```bash
|
||
ls -la lib/generated/api/
|
||
ls -la lib/generated/api_models/
|
||
```
|
||
|
||
3. **在代码中使用**
|
||
|
||
打开 `lib/main.dart`，取消注释以下行：
|
||
```dart
|
||
import 'generated/api/api_client.dart';
|
||
```
|
||
|
||
然后使用生成的 API：
|
||
```dart
|
||
final dio = Dio();
|
||
final apiClient = ApiClient(dio);
|
||
|
||
// 调用 API
|
||
final response = await apiClient.petApi.getPetById(petId: 1);
|
||
```
|
||
|
||
## 🎯 理解项目结构
|
||
|
||
```
|
||
example/as_dev_dependency/
|
||
├── pubspec.yaml ← 定义依赖
|
||
├── generator_config.yaml ← 配置生成器
|
||
├── generate_api.sh ← 生成脚本
|
||
├── lib/
|
||
│ ├── common/ ← 基础类型定义
|
||
│ │ ├── api_response.dart
|
||
│ │ └── paged_response.dart
|
||
│ ├── generated/ ← 生成的代码（自动）
|
||
│ │ ├── api/
|
||
│ │ └── api_models/
|
||
│ └── main.dart ← 应用入口
|
||
└── README.md ← 详细文档
|
||
```
|
||
|
||
## 💡 核心文件说明
|
||
|
||
### 1. `pubspec.yaml` - 依赖配置
|
||
|
||
```yaml
|
||
dev_dependencies:
|
||
swagger_generator_flutter:
|
||
path: ../../ # 示例使用相对路径
|
||
```
|
||
|
||
在实际项目中使用：
|
||
```yaml
|
||
dev_dependencies:
|
||
swagger_generator_flutter:
|
||
git:
|
||
url: https://github.com/your-org/swagger_generator_flutter.git
|
||
ref: main
|
||
```
|
||
|
||
### 2. `generator_config.yaml` - 生成器配置
|
||
|
||
关键配置项：
|
||
```yaml
|
||
input:
|
||
swagger_url: "https://petstore3.swagger.io/api/v3/openapi.json"
|
||
|
||
output:
|
||
base_dir: "./lib/generated"
|
||
|
||
generation:
|
||
api:
|
||
enabled: true
|
||
use_retrofit: true
|
||
models:
|
||
enabled: true
|
||
use_json_serializable: true
|
||
```
|
||
|
||
### 3. `generate_api.sh` - 自动化脚本
|
||
|
||
执行流程：
|
||
1. ✅ 生成 API 代码
|
||
2. ✅ 运行 build_runner
|
||
3. ✅ 格式化代码
|
||
4. ✅ 分析代码
|
||
|
||
## 🔄 工作流程
|
||
|
||
```mermaid
|
||
graph LR
|
||
A[修改配置] --> B[运行生成脚本]
|
||
B --> C[生成 API 代码]
|
||
C --> D[运行 build_runner]
|
||
D --> E[格式化代码]
|
||
E --> F[在项目中使用]
|
||
```
|
||
|
||
## 📋 常用命令速查
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `make install` | 安装依赖 |
|
||
| `make generate` | 生成 API 代码 |
|
||
| `make build` | 生成并构建 |
|
||
| `make watch` | 监听模式 |
|
||
| `make clean` | 清理生成的文件 |
|
||
| `make run` | 运行应用 |
|
||
|
||
## 🎓 学习路径
|
||
|
||
1. ✅ **快速开始**（当前文档）
|
||
2. 📖 [完整 README](README.md) - 详细项目说明
|
||
3. 📚 [使用指南](../../USAGE_AS_DEV_DEPENDENCY.md) - 深入教程
|
||
4. 🔧 [配置模板](../../generator_config.template.yaml) - 配置参考
|
||
5. 📖 [项目文档](../../README.md) - 完整项目文档
|
||
|
||
## ❓ 遇到问题？
|
||
|
||
**生成失败？**
|
||
```bash
|
||
# 检查配置文件
|
||
cat generator_config.yaml
|
||
|
||
# 重新安装依赖
|
||
flutter pub get
|
||
|
||
# 清理后重新生成
|
||
make clean
|
||
make build
|
||
```
|
||
|
||
**运行错误？**
|
||
```bash
|
||
# 检查是否已生成代码
|
||
ls lib/generated/
|
||
|
||
# 检查是否运行了 build_runner
|
||
ls lib/generated/**/*.g.dart
|
||
```
|
||
|
||
**更多帮助？**
|
||
- 查看 [README.md](README.md)
|
||
- 查看 [故障排除](README.md#-故障排除)
|
||
- 提交 Issue
|
||
|
||
## 🎉 下一步
|
||
|
||
现在您已经了解了基础用法，可以：
|
||
|
||
1. 🔧 修改 `generator_config.yaml` 配置
|
||
2. 📝 连接您自己的 Swagger API
|
||
3. 🚀 在实际项目中集成
|
||
4. 📚 阅读完整文档了解高级功能
|
||
|
||
祝编码愉快！ 🎊
|
||
|