wangyang

8.0 KiB

Raw Blame History

作为 dev_dependencies 使用指南

本工具可以作为 dev_dependencies 集成到您的 Flutter/Dart 项目中，实现自动化的 Swagger API 代码生成。

📦 安装步骤

1. 添加依赖

在您的项目的 pubspec.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. 安装依赖包

flutter pub get
# 或
dart pub get

📝 配置文件

在您的项目根目录创建 generator_config.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: 使用命令行直接执行

# 生成所有文件（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):

#!/bin/bash
echo "🚀 开始生成 API 代码..."
dart run swagger_generator_flutter generate --all
echo "✅ 代码生成完成！"

或创建 generate_api.bat (Windows):

@echo off
echo 🚀 开始生成 API 代码...
dart run swagger_generator_flutter generate --all
echo ✅ 代码生成完成！

给脚本添加执行权限并运行：

# macOS/Linux
chmod +x generate_api.sh
./generate_api.sh

# Windows
generate_api.bat

方式 3: 集成到构建流程

在 pubspec.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 包含以下依赖：

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 文件：

# 一次性构建
dart run build_runner build --delete-conflicting-outputs

# 监听模式（开发时推荐）
dart run build_runner watch --delete-conflicting-outputs

💡 工作流程示例

完整的代码生成工作流程：

# 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 示例

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. 权限问题

问题: 无法写入生成的文件

解决:

📚 更多资源

🤝 贡献

如果您发现问题或有改进建议，欢迎提交 Issue 或 Pull Request。

8.0 KiB Raw Blame History Unescape Escape