353 lines
8.0 KiB
Markdown
353 lines
8.0 KiB
Markdown
# 作为 dev_dependencies 使用指南
|
||
|
||
本工具可以作为 `dev_dependencies` 集成到您的 Flutter/Dart 项目中，实现自动化的 Swagger API 代码生成。
|
||
|
||
## 📦 安装步骤
|
||
|
||
### 1. 添加依赖
|
||
|
||
在您的项目的 `pubspec.yaml` 中添加：
|
||
|
||
```yaml
|
||
dev_dependencies:
|
||
swagger_generator_flutter:
|
||
git:
|
||
url: https://github.com/your-org/swagger_generator_flutter.git
|
||
ref: develop # 或者指定特定的 tag/branch
|
||
|
||
# 或者使用本地路径（开发时）
|
||
# swagger_generator_flutter:
|
||
# path: ../swagger_generator_flutter
|
||
```
|
||
|
||
### 2. 安装依赖包
|
||
|
||
```bash
|
||
flutter pub get
|
||
# 或
|
||
dart pub get
|
||
```
|
||
|
||
## 📝 配置文件
|
||
|
||
在您的项目根目录创建 `generator_config.yaml` 配置文件：
|
||
|
||
```yaml
|
||
# Swagger 代码生成器配置文件
|
||
|
||
# 基本配置
|
||
generator:
|
||
name: "my_project_generator"
|
||
version: "1.0"
|
||
author: "Your Name"
|
||
copyright: "Copyright (C) 2025 Your Company. All rights reserved."
|
||
|
||
# 输入配置
|
||
input:
|
||
# Swagger 文档源（支持多版本）
|
||
swagger_urls:
|
||
# 简写形式：直接列出 URL
|
||
- "https://your-api.com/swagger/v1/swagger.json"
|
||
- "https://your-api.com/swagger/v2/swagger.json"
|
||
|
||
# 完整形式：可以控制每个版本的启用状态
|
||
# - url: "https://your-api.com/swagger/v1/swagger.json"
|
||
# enabled: true # 可选，是否启用此版本（默认: true）
|
||
|
||
# 验证配置
|
||
validate_schema: true
|
||
strict_mode: true
|
||
|
||
# 输出配置
|
||
output:
|
||
# 输出目录
|
||
base_dir: "./lib/generated"
|
||
api_dir: "./lib/generated/api"
|
||
models_dir: "./lib/generated/api_models"
|
||
|
||
# 文件命名
|
||
api_file_suffix: "_api.dart"
|
||
model_file_suffix: ".dart"
|
||
|
||
# 是否按 tag 分组
|
||
split_by_tags: true
|
||
|
||
# 代码生成配置
|
||
generation:
|
||
# API 接口配置
|
||
api:
|
||
enabled: true
|
||
use_retrofit: true
|
||
use_dio: true
|
||
parser: "JsonSerializable"
|
||
|
||
# 基础类型配置（根据您的项目调整）
|
||
base_result_type: "BaseResult"
|
||
base_page_result_type: "BasePageResult"
|
||
base_result_import: "package:your_project/common/models/base_result.dart"
|
||
base_page_result_import: "package:your_project/common/models/base_page_result.dart"
|
||
|
||
# 方法命名
|
||
method_naming: "camelCase"
|
||
|
||
# 数据模型配置
|
||
models:
|
||
enabled: true
|
||
use_json_serializable: true
|
||
|
||
# JsonSerializable 配置
|
||
json_serializable:
|
||
checked: true
|
||
include_if_null: false
|
||
explicit_to_json: true
|
||
|
||
# 类命名
|
||
class_naming: "PascalCase"
|
||
field_naming: "camelCase"
|
||
|
||
# 构造函数配置
|
||
use_const_constructor: true
|
||
required_for_non_nullable: true
|
||
```
|
||
|
||
## 🚀 使用方法
|
||
|
||
### 方式 1: 使用命令行直接执行
|
||
|
||
```bash
|
||
# 生成所有文件（API、模型、文档）
|
||
dart run swagger_generator_flutter generate --all
|
||
|
||
# 只生成模型
|
||
dart run swagger_generator_flutter generate --models
|
||
|
||
# 只生成 API 接口
|
||
dart run swagger_generator_flutter generate --api
|
||
|
||
# 只生成文档
|
||
dart run swagger_generator_flutter generate --docs
|
||
|
||
# 指定输出目录
|
||
dart run swagger_generator_flutter generate --all --output-dir lib/generated
|
||
```
|
||
|
||
### 方式 2: 创建便捷脚本
|
||
|
||
在项目根目录创建 `generate_api.sh` (macOS/Linux):
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
echo "🚀 开始生成 API 代码..."
|
||
dart run swagger_generator_flutter generate --all
|
||
echo "✅ 代码生成完成！"
|
||
```
|
||
|
||
或创建 `generate_api.bat` (Windows):
|
||
|
||
```batch
|
||
@echo off
|
||
echo 🚀 开始生成 API 代码...
|
||
dart run swagger_generator_flutter generate --all
|
||
echo ✅ 代码生成完成！
|
||
```
|
||
|
||
给脚本添加执行权限并运行：
|
||
|
||
```bash
|
||
# macOS/Linux
|
||
chmod +x generate_api.sh
|
||
./generate_api.sh
|
||
|
||
# Windows
|
||
generate_api.bat
|
||
```
|
||
|
||
### 方式 3: 集成到构建流程
|
||
|
||
在 `pubspec.yaml` 中添加自定义脚本：
|
||
|
||
```yaml
|
||
# 可以在 scripts 字段添加（如果使用 melos 或其他工具）
|
||
scripts:
|
||
generate: dart run swagger_generator_flutter generate --all
|
||
```
|
||
|
||
## 📋 命令选项
|
||
|
||
| 选项 | 简写 | 说明 |
|
||
|------|------|------|
|
||
| `--all` | `-a` | 生成所有文件（默认） |
|
||
| `--api` | `-r` | 生成 Retrofit 风格 API 接口 |
|
||
| `--models` | `-m` | 生成数据模型 |
|
||
| `--docs` | `-d` | 生成 API 文档 |
|
||
| `--simple` | `-s` | 使用简洁版模型生成 |
|
||
| `--split-by-tags` | `-t` | 按 tags 分组生成多个 API 文件 |
|
||
| `--output-dir` | `-o` | 指定输出目录 |
|
||
| `--help` | `-h` | 显示帮助信息 |
|
||
|
||
## 📂 生成的文件结构
|
||
|
||
执行生成命令后，将在输出目录创建以下结构：
|
||
|
||
```
|
||
lib/generated/
|
||
├── api/
|
||
│ ├── v1/
|
||
│ │ ├── user_api.dart
|
||
│ │ ├── product_api.dart
|
||
│ │ └── index.dart
|
||
│ ├── v2/
|
||
│ │ ├── user_api_v2.dart
|
||
│ │ └── index.dart
|
||
│ └── api_client.dart
|
||
├── api_models/
|
||
│ ├── request/
|
||
│ │ ├── create_user_request.dart
|
||
│ │ └── index.dart
|
||
│ ├── result/
|
||
│ │ ├── user_result.dart
|
||
│ │ └── index.dart
|
||
│ ├── parameters/
|
||
│ │ ├── get_user_list_parameters.dart
|
||
│ │ └── index.dart
|
||
│ └── index.dart
|
||
├── api_documentation.md
|
||
└── SUMMARY.md
|
||
```
|
||
|
||
## 🔧 必需的项目依赖
|
||
|
||
确保您的项目 `pubspec.yaml` 包含以下依赖：
|
||
|
||
```yaml
|
||
dependencies:
|
||
# HTTP 客户端
|
||
dio: ^5.0.0
|
||
retrofit: ^4.0.0
|
||
|
||
# JSON 序列化
|
||
json_annotation: ^4.8.0
|
||
|
||
dev_dependencies:
|
||
# 代码生成
|
||
build_runner: ^2.4.7
|
||
retrofit_generator: ^8.0.0
|
||
json_serializable: ^6.7.1
|
||
```
|
||
|
||
## 🔄 运行 build_runner
|
||
|
||
生成代码后，需要运行 `build_runner` 生成 `.g.dart` 文件：
|
||
|
||
```bash
|
||
# 一次性构建
|
||
dart run build_runner build --delete-conflicting-outputs
|
||
|
||
# 监听模式（开发时推荐）
|
||
dart run build_runner watch --delete-conflicting-outputs
|
||
```
|
||
|
||
## 💡 工作流程示例
|
||
|
||
完整的代码生成工作流程：
|
||
|
||
```bash
|
||
# 1. 生成 API 代码
|
||
dart run swagger_generator_flutter generate --all
|
||
|
||
# 2. 运行 build_runner 生成序列化代码
|
||
dart run build_runner build --delete-conflicting-outputs
|
||
|
||
# 3. 格式化代码（可选）
|
||
dart format lib/generated
|
||
|
||
# 4. 分析代码（可选）
|
||
dart analyze lib/generated
|
||
```
|
||
|
||
## 🎯 CI/CD 集成
|
||
|
||
在您的 CI/CD 流程中添加代码生成步骤：
|
||
|
||
### GitHub Actions 示例
|
||
|
||
```yaml
|
||
name: Generate API Code
|
||
|
||
on:
|
||
push:
|
||
branches: [ main, develop ]
|
||
pull_request:
|
||
branches: [ main, develop ]
|
||
|
||
jobs:
|
||
generate:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
|
||
- uses: subosito/flutter-action@v2
|
||
with:
|
||
flutter-version: '3.16.0'
|
||
channel: 'stable'
|
||
|
||
- name: Install dependencies
|
||
run: flutter pub get
|
||
|
||
- name: Generate API code
|
||
run: dart run swagger_generator_flutter generate --all
|
||
|
||
- name: Run build_runner
|
||
run: dart run build_runner build --delete-conflicting-outputs
|
||
|
||
- name: Check for 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. 配置文件未找到
|
||
|
||
**问题**: 工具无法读取 `generator_config.yaml`
|
||
|
||
**解决**: 确保配置文件在项目根目录，与 `pubspec.yaml` 同级
|
||
|
||
### 3. 生成的代码有编译错误
|
||
|
||
**问题**: 生成的代码缺少导入或有类型错误
|
||
|
||
**解决**:
|
||
- 检查 `generator_config.yaml` 中的导入配置
|
||
- 确保项目中已定义 `BaseResult` 等基础类型
|
||
- 运行 `dart run build_runner build --delete-conflicting-outputs`
|
||
|
||
### 4. 权限问题
|
||
|
||
**问题**: 无法写入生成的文件
|
||
|
||
**解决**:
|
||
- 检查输出目录权限
|
||
- 确保输出目录存在或工具有创建权限
|
||
|
||
## 📚 更多资源
|
||
|
||
- [完整文档](docs/USAGE_GUIDE.md)
|
||
- [项目概览](docs/PROJECT_OVERVIEW.md)
|
||
- [示例项目](example/)
|
||
|
||
## 🤝 贡献
|
||
|
||
如果您发现问题或有改进建议，欢迎提交 Issue 或 Pull Request。
|
||
|
||
## 📄 许可证
|
||
|
||
Copyright (C) 2025 YuanXuan. All rights reserved.
|
||
|