swagger_generator_flutter/CONTRIBUTING.md

# 贡献指南

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

## 🤝 如何贡献

### 报告问题

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

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

### 提交代码

1. **Fork 项目**
   ```bash
   git clone https://github.com/your-username/swagger_generator_flutter.git
   cd swagger_generator_flutter
   ```

2. **创建分支**
   ```bash
   git checkout -b feature/your-feature-name
   # 或
   git checkout -b fix/your-bug-fix
   ```

3. **安装依赖**
   ```bash
   flutter pub get
   ```

4. **进行更改**
   - 遵循项目的代码风格
   - 添加必要的测试
   - 更新相关文档

5. **运行测试**
   ```bash
   dart test
   ```

6. **提交更改**
   ```bash
   git add .
   git commit -m "feat: add new feature" # 遵循 Conventional Commits
   ```

7. **推送分支**
   ```bash
   git push origin feature/your-feature-name
   ```

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

## 📝 代码风格

### Dart 代码风格

我们遵循 [Dart 官方代码风格指南](https://dart.dev/guides/language/effective-dart/style)：

```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`)

### 注释规范

```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/             # 测试数据
```

### 编写测试

```dart
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%+ 的测试覆盖率：

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

## 📚 文档贡献

### 文档类型

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

### 文档风格

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

## 🔄 发布流程

### 版本号规范

我们遵循 [语义化版本](https://semver.org/lang/zh-CN/)：

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

### 提交信息规范

我们使用 [Conventional Commits](https://www.conventionalcommits.org/zh-hans/)：

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

[可选的正文]

[可选的脚注]
```

**类型：**
- `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

### 推荐工具

- VS Code 或 IntelliJ IDEA
- Dart 和 Flutter 插件
- Git hooks (pre-commit)

### 环境配置

1. **克隆项目**
   ```bash
   git clone https://github.com/your-repo/swagger_generator_flutter.git
   cd swagger_generator_flutter
   ```

2. **安装依赖**
   ```bash
   flutter pub get
   ```

3. **运行测试**
   ```bash
   dart test
   ```

4. **运行示例**
   ```bash
   dart run example/basic_usage.dart
   ```

### 开发工作流

1. 创建功能分支
2. 编写代码和测试
3. 运行所有测试
4. 更新文档
5. 提交代码
6. 创建 Pull Request

## 🎯 贡献领域

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

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

### 中优先级
- ✨ 新功能开发
- 🔧 工具改进
- 📝 示例代码
- 🌐 国际化支持

### 低优先级
- 🎨 UI/UX 改进
- 📦 依赖更新
- 🔍 代码质量提升

## 📞 联系我们

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

## 📄 许可证

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

## 🙏 致谢

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

### 贡献者列表

<!-- 这里会自动生成贡献者列表 -->

---

再次感谢您的贡献！🎉