wangyang

swagger_generator_flutter

Fork 0

7.4 KiB

Raw Blame History

贡献指南

感谢您对 Swagger Generator Flutter 项目的关注！我们欢迎各种形式的贡献。

🤝 如何贡献

报告问题

如果您发现了 bug 或有功能建议，请：

检查现有 Issues 是否已有相关报告
如果没有，请创建新的 Issue，包含：
- 清晰的标题和描述
- 重现步骤（如果是 bug）
- 期望的行为
- 实际的行为
- 环境信息（Dart/Flutter 版本等）
- 相关的代码片段或错误日志

提交代码

Fork 项目

git clone https://github.com/your-username/swagger_generator_flutter.git
cd swagger_generator_flutter

创建分支

git checkout -b feature/your-feature-name
# 或
git checkout -b fix/your-bug-fix

安装依赖
```
flutter pub get
```
进行更改
- 遵循项目的代码风格
- 添加必要的测试
- 更新相关文档
运行测试
```
dart test
```

提交更改

git add .
git commit -m "feat: add new feature" # 遵循 Conventional Commits

推送分支

git push origin feature/your-feature-name

创建 Pull Request
- 提供清晰的 PR 描述
- 链接相关的 Issues
- 确保所有检查通过

📝 代码风格

Dart 代码风格

我们遵循 Dart 官方代码风格指南：

// ✅ 好的示例
class ApiGenerator {
  final String className;
  final bool generateModels;
  
  ApiGenerator({
    required this.className,
    this.generateModels = true,
  });
  
  String generateCode() {
    // 实现逻辑
    return 'generated code';
  }
}

// ❌ 不好的示例
class api_generator {
  String class_name;
  bool generate_models;
  
  api_generator(this.class_name, this.generate_models);
  
  String generate_code() {
    return "generated code";
  }
}

命名约定

类名: PascalCase (ApiGenerator)
方法名: camelCase (generateCode)
变量名: camelCase (className)
常量: SCREAMING_SNAKE_CASE (DEFAULT_TIMEOUT)
文件名: snake_case (api_generator.dart)

注释规范

/// 生成 Retrofit API 代码的生成器
/// 
/// 支持多种配置选项，包括：
/// - 模块化 API 生成
/// - 基础响应类型
/// - 分页支持
/// 
/// 示例用法：
/// ```dart
/// final generator = RetrofitApiGenerator(
///   className: 'ApiService',
///   splitByTags: true,
/// );
/// ```
class RetrofitApiGenerator {
  /// API 服务类名
  final String className;
  
  /// 是否按标签分割 API
  final bool splitByTags;
  
  /// 创建 Retrofit API 生成器
  /// 
  /// [className] 生成的 API 服务类名
  /// [splitByTags] 是否按标签分割成多个 API 类
  RetrofitApiGenerator({
    this.className = 'ApiService',
    this.splitByTags = false,
  });
}

🧪 测试指南

测试结构

tests/
├── unit/                    # 单元测试
│   ├── generators/         # 生成器测试
│   ├── parsers/           # 解析器测试
│   └── validators/        # 验证器测试
├── integration/           # 集成测试
└── fixtures/             # 测试数据

编写测试

import 'package:test/test.dart';
import 'package:swagger_generator_flutter/swagger_generator_flutter.dart';

void main() {
  group('RetrofitApiGenerator', () {
    late RetrofitApiGenerator generator;
    
    setUp(() {
      generator = RetrofitApiGenerator(
        className: 'TestApi',
        splitByTags: false,
      );
    });
    
    test('should generate basic API structure', () {
      // Arrange
      final document = createTestDocument();
      
      // Act
      final result = generator.generateFromDocument(document);
      
      // Assert
      expect(result, contains('abstract class TestApi'));
      expect(result, contains('@RestApi()'));
    });
    
    test('should handle empty document', () {
      // Arrange
      final emptyDocument = createEmptyDocument();
      
      // Act & Assert
      expect(() => generator.generateFromDocument(emptyDocument), 
             returnsNormally);
    });
  });
}

SwaggerDocument createTestDocument() {
  return SwaggerDocument(
    title: 'Test API',
    version: '1.0.0',
    description: 'Test',
    servers: [],
    components: ApiComponents(schemas: {}, securitySchemes: {}),
    paths: {},
    models: {},
    controllers: {},
    security: [],
  );
}

测试覆盖率

我们目标是保持 90%+ 的测试覆盖率：

# 运行测试并生成覆盖率报告
dart test --coverage=coverage
genhtml coverage/lcov.info -o coverage/html

📚 文档贡献

文档类型

API 文档: 代码中的 dartdoc 注释
用户指南: README.md 和 docs/ 目录
示例代码: example/ 目录
迁移指南: MIGRATION_GUIDE.md

文档风格

使用清晰、简洁的语言
提供实际的代码示例
包含常见用例和最佳实践
保持文档与代码同步

🔄 发布流程

版本号规范

我们遵循语义化版本：

主版本号: 不兼容的 API 修改
次版本号: 向下兼容的功能性新增
修订号: 向下兼容的问题修正

提交信息规范

我们使用 Conventional Commits：

<类型>[可选的作用域]: <描述>

[可选的正文]

[可选的脚注]

类型：

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 重构
test: 测试相关
chore: 构建过程或辅助工具的变动

示例：

feat(generator): add support for file upload

- Add MultipartFile support in OptimizedRetrofitGenerator
- Generate proper @MultiPart annotations
- Update tests and documentation

Closes #123

🏗️ 开发环境设置

必需工具

Dart SDK 3.0+
Flutter SDK 3.0+
Git

环境配置

克隆项目

git clone https://github.com/your-repo/swagger_generator_flutter.git
cd swagger_generator_flutter

安装依赖
```
flutter pub get
```
运行测试
```
dart test
```
运行示例
```
dart run example/basic_usage.dart
```

开发工作流

创建功能分支
编写代码和测试
运行所有测试
更新文档
提交代码
创建 Pull Request

🎯 贡献领域

我们特别欢迎以下领域的贡献：

高优先级

🐛 Bug 修复
📚 文档改进
🧪 测试覆盖率提升
🚀 性能优化

中优先级

✨ 新功能开发
🔧 工具改进
📝 示例代码
🌐 国际化支持

低优先级

🎨 UI/UX 改进
📦 依赖更新
🔍 代码质量提升

📞 联系我们

GitHub Issues: 报告 bug 和功能请求
GitHub Discussions: 一般讨论和问题
Email: maintainer@example.com

📄 许可证

通过贡献代码，您同意您的贡献将在与项目相同的 MIT 许可证下授权。

🙏 致谢

感谢所有贡献者的努力！您的贡献让这个项目变得更好。

贡献者列表

再次感谢您的贡献！🎉

7.4 KiB Raw Blame History Unescape Escape