# 作为 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.