373 lines
10 KiB
YAML
373 lines
10 KiB
YAML
# Swagger 代码生成器配置文件模板
|
||
# 复制此文件到您的项目根目录，重命名为 generator_config.yaml，并根据需要修改
|
||
|
||
# 基本配置
|
||
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
|
||
|
||
# 只生成指定 tags 的 API 和模型（可选）
|
||
# 如果不指定或为空，则生成所有 tags
|
||
# 如果某个 endpoint 有多个 tags，只要其中一个在列表中就会生成
|
||
included_tags:
|
||
# - "User"
|
||
# - "Pet"
|
||
# - "Store"
|
||
|
||
# 从代码生成中排除指定的 tags
|
||
# 适用于内部、废弃或不需要的 API
|
||
# 如果一个 endpoint 的所有 tags 都被排除，则该 endpoint 不会生成
|
||
excluded_tags:
|
||
# - "Internal"
|
||
# - "Deprecated"
|
||
# - "Legacy"
|
||
|
||
# 跳过的目录列表（这些目录下的文件将不会被生成）
|
||
# 支持相对路径和绝对路径，支持目录名或完整路径
|
||
ignored_directories:
|
||
# - "api/v1" # 跳过 v1 版本的 API
|
||
# - "api_models/request" # 跳过请求模型目录
|
||
# - "./lib/generated/api/v2" # 跳过特定路径
|
||
|
||
# 跳过的文件名列表（这些文件将不会被生成）
|
||
# 支持精确匹配、通配符匹配和模式匹配
|
||
ignored_files:
|
||
# 精确匹配文件名
|
||
# - "user_api.dart" # 跳过名为 user_api.dart 的文件
|
||
# - "mobile_manager_api.dart" # 跳过指定文件
|
||
|
||
# 通配符匹配（支持前缀和后缀）
|
||
# - "*_api.dart" # 跳过所有以 _api.dart 结尾的文件
|
||
# - "user*.dart" # 跳过所有以 user 开头的 .dart 文件
|
||
# - "*manager*" # 跳过所有包含 manager 的文件名
|
||
|
||
# 示例：跳过所有 v1 版本的 API 文件
|
||
# - "*_api_v1.dart"
|
||
# - "*V1*.dart"
|
||
|
||
# 代码生成配置
|
||
generation:
|
||
# API 接口配置
|
||
api:
|
||
enabled: true
|
||
use_retrofit: true
|
||
use_dio: true
|
||
parser: "JsonSerializable"
|
||
|
||
# API Client 配置
|
||
# 主 API 客户端类的名称和文件名配置
|
||
client:
|
||
class_name: "ApiClient" # API 客户端类名（默认: ApiClient）
|
||
file_name: "api_client" # API 客户端文件名（默认: api_client，不含 .dart 后缀）
|
||
|
||
# 版本提取配置（多版本支持）
|
||
version_extraction:
|
||
# 版本提取正则表达式模式
|
||
# 默认: "/api/v(\\d+)/" 匹配 /api/v1/, /api/v2/ 等
|
||
pattern: "/api/v(\\d+)/"
|
||
|
||
# 默认版本（当无法从路径提取版本时使用）
|
||
default_version: "v1"
|
||
|
||
# 基础类型配置（根据您的项目调整）
|
||
# 如果您的项目有统一的响应模型，请在此处配置
|
||
base_result_type: "BaseResult" # 基础响应模型名称
|
||
base_page_result_type: "BasePageResult" # 分页响应模型名称
|
||
|
||
# 基础模型的导入路径（可选）
|
||
# 如果提供了路径，将在 api_models/index.dart 中自动导出
|
||
# 如果留空，则不会生成导出语句
|
||
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" # camelCase, snake_case
|
||
|
||
# CancelToken 支持（可选）
|
||
# 启用后，为每个 API 方法添加可选的 CancelToken 参数，用于取消请求
|
||
# 生成的方法签名示例：
|
||
# Future<Result> getUser({
|
||
# @Query('id') int? id,
|
||
# @CancelRequest() CancelToken? cancelToken, // <- 自动添加
|
||
# });
|
||
cancel_token_support: false # 默认: false
|
||
|
||
# 数据模型配置
|
||
models:
|
||
enabled: true
|
||
use_json_serializable: true
|
||
|
||
# JsonSerializable 配置
|
||
json_serializable:
|
||
checked: true
|
||
include_if_null: false
|
||
explicit_to_json: true
|
||
|
||
# 类命名
|
||
class_naming: "PascalCase" # PascalCase, snake_case
|
||
field_naming: "camelCase" # camelCase, snake_case
|
||
|
||
# 构造函数配置
|
||
use_const_constructor: true
|
||
required_for_non_nullable: true
|
||
|
||
# 枚举键名映射配置（可选）
|
||
# 用于为枚举值定义有意义的键名和描述
|
||
# 优先级：配置文件映射 > x-enum-varnames > 智能生成
|
||
#
|
||
# 使用场景：
|
||
# 1. 后端不支持 x-enum-varnames 扩展字段
|
||
# 2. 需要覆盖 Swagger 文档中的枚举键名
|
||
# 3. 需要为枚举值添加自定义描述
|
||
#
|
||
# 格式:
|
||
# enum_key_mappings:
|
||
# 枚举名称:
|
||
# - value: 枚举值（数字或字符串）
|
||
# name: 枚举键名（大写下划线命名）
|
||
# description: 枚举描述（可选）
|
||
#
|
||
# 示例:
|
||
# enum_key_mappings:
|
||
# SysTaskTypeEnums:
|
||
# - value: 1
|
||
# name: SPOT_CHECK
|
||
# description: 抽查
|
||
# - value: 2
|
||
# name: CULTURAL
|
||
# description: 文创建设
|
||
# - value: 3
|
||
# name: CLASS_CADRE_MEETING
|
||
# description: 班干部会议
|
||
#
|
||
# UserStatus:
|
||
# - value: "active"
|
||
# name: ACTIVE
|
||
# description: 活跃用户
|
||
# - value: "inactive"
|
||
# name: INACTIVE
|
||
# description: 非活跃用户
|
||
# - value: "banned"
|
||
# name: BANNED
|
||
# description: 已封禁
|
||
#
|
||
enum_key_mappings:
|
||
# 在此处添加您的枚举映射配置
|
||
# SysTaskTypeEnums:
|
||
# - value: 1
|
||
# name: SPOT_CHECK
|
||
# description: 抽查
|
||
# - value: 2
|
||
# name: CULTURAL
|
||
# description: 文创建设
|
||
|
||
# 类型映射配置
|
||
type_mapping:
|
||
# OpenAPI -> Dart 类型映射
|
||
string: "String"
|
||
integer: "int"
|
||
number: "double"
|
||
boolean: "bool"
|
||
array: "List"
|
||
object: "Map<String, dynamic>"
|
||
|
||
# 特殊类型处理
|
||
date: "DateTime"
|
||
date-time: "DateTime"
|
||
binary: "Uint8List"
|
||
|
||
# 导入管理配置
|
||
imports:
|
||
# 按需导入
|
||
on_demand: true
|
||
|
||
# 自动排序
|
||
auto_sort: true
|
||
|
||
# 分组导入
|
||
group_imports: true
|
||
|
||
# 标准库导入
|
||
dart_imports:
|
||
- "dart:convert"
|
||
- "dart:typed_data"
|
||
|
||
# 第三方库导入
|
||
package_imports:
|
||
- "package:dio/dio.dart"
|
||
- "package:retrofit/retrofit.dart"
|
||
- "package:json_annotation/json_annotation.dart"
|
||
|
||
# 验证配置
|
||
validation:
|
||
# 严格模式
|
||
strict_mode: true
|
||
|
||
# 检查项
|
||
checks:
|
||
- "schema_exists"
|
||
- "ref_resolution"
|
||
- "type_consistency"
|
||
- "nullable_correctness"
|
||
- "required_fields"
|
||
|
||
# 错误处理
|
||
on_error: "warn" # fail, warn, ignore
|
||
|
||
# 警告处理
|
||
on_warning: "log" # fail, log, ignore
|
||
|
||
# 优化配置
|
||
optimization:
|
||
# 代码优化
|
||
remove_unused_imports: true
|
||
optimize_imports: true
|
||
|
||
# 性能优化
|
||
cache_schemas: true
|
||
parallel_generation: false
|
||
|
||
# 内存优化
|
||
lazy_loading: true
|
||
|
||
# 调试配置
|
||
debug:
|
||
# 详细日志
|
||
verbose: false
|
||
|
||
# 调试输出
|
||
debug_output: false
|
||
|
||
# 性能监控
|
||
performance_monitoring: false
|
||
|
||
# 生成统计
|
||
generation_stats: true
|
||
|
||
# 兼容性配置
|
||
compatibility:
|
||
# Dart 版本
|
||
dart_version: ">=3.0.0"
|
||
|
||
# Flutter 版本
|
||
flutter_version: ">=3.10.0"
|
||
|
||
# 依赖版本
|
||
dependencies:
|
||
dio: "^5.0.0"
|
||
retrofit: "^4.0.0"
|
||
json_annotation: "^4.8.0"
|
||
|
||
dev_dependencies:
|
||
build_runner: "^2.3.0"
|
||
retrofit_generator: "^8.0.0"
|
||
json_serializable: "^6.6.0"
|
||
|
||
# 自定义配置
|
||
custom:
|
||
# 项目特定配置
|
||
project_name: "your_project" # 修改为您的项目名称
|
||
|
||
# 特殊处理规则
|
||
special_handling:
|
||
# 健康检查接口返回 void
|
||
health_check_paths:
|
||
- "/health"
|
||
- "/healthcheck"
|
||
- "/api/health"
|
||
|
||
# 分页接口参数名
|
||
pagination_params:
|
||
- "page"
|
||
- "size"
|
||
- "limit"
|
||
- "offset"
|
||
- "pageIndex"
|
||
- "pageSize"
|
||
|
||
# 忽略的路径
|
||
ignored_paths:
|
||
- "/swagger"
|
||
- "/docs"
|
||
|
||
# 忽略的 tags
|
||
ignored_tags:
|
||
- "Internal"
|
||
- "Debug"
|
||
|
||
# 模板配置
|
||
templates:
|
||
# 文件头模板
|
||
# 支持模板变量:
|
||
# {fileName} - 文件名（如 "user_api.dart"）
|
||
# {fileType} - 文件类型描述（如 "API 接口定义"、"模型定义"）
|
||
# {swaggerUrl} - Swagger 文档 URL
|
||
# {generatorName} - 生成器名称（从 generator.name 读取）
|
||
# {author} - 作者（从 generator.author 读取）
|
||
# {copyright} - 版权信息（从 generator.copyright 读取）
|
||
file_header: |
|
||
// {fileType}
|
||
// 基于 Swagger API 文档: {swaggerUrl}
|
||
// 由 {generatorName} by {author} 生成
|
||
// {copyright}
|
||
|
||
# API 类模板
|
||
# 支持模板变量:
|
||
# {tagName} - Tag 名称（如 "User"、"Task"）
|
||
# {className} - 类名（如 "UserApi"、"TaskApi"）
|
||
api_class: |
|
||
/// {tagName} API 接口
|
||
/// 负责处理 {tagName} 相关的接口
|
||
@RestApi(parser: Parser.JsonSerializable)
|
||
abstract class {className} {
|
||
factory {className}(Dio dio, {String? baseUrl}) = _{className};
|
||
}
|
||
|
||
# 模型类模板
|
||
# 支持模板变量:
|
||
# {className} - 类名（如 "User"、"Task"）
|
||
# {constructorParams} - 构造函数参数列表
|
||
model_class: |
|
||
@JsonSerializable(checked: true, includeIfNull: false)
|
||
class {className} {
|
||
const {className}({constructorParams});
|
||
|
||
factory {className}.fromJson(Map<String, dynamic> json) =>
|
||
_${className}FromJson(json);
|
||
|
||
Map<String, dynamic> toJson() => _${className}ToJson(this);
|
||
}
|
||
|