ApiVersionAuto 1.0.0

ApiVersionAuto

🚀 Automate API versioning in .NET projects by detecting breaking changes and generating new API versions using Roslyn analyzers.

📋 Overview

ApiVersionAuto is a powerful .NET library that automatically detects breaking changes in your API code and suggests appropriate version increments. It uses Roslyn analyzers to scan your codebase and identify potential breaking changes, helping you maintain API versioning best practices.

✨ Key Features

• 🔍 Auto-detects breaking changes in API contracts using Roslyn
• 📈 Generates new API versions automatically based on semantic versioning
• 🎛️ Attribute-based overrides for manual control and exclusions
• 🔧 Integrates with ASP.NET Core routing and middleware
• 📝 Changelog and diff generation for better documentation
• 🛡️ Prevents accidental breaking changes from reaching production
• 📊 Comprehensive reporting with severity levels and migration guides

🚀 Quick Start

Installation

dotnet add package ApiVersionAuto

Basic Usage

using ApiVersionAuto;
using ApiVersionAuto.Analyzers;
using ApiVersionAuto.Generators;

// Configure the analyzer engine
var engine = new AnalyzerEngine()
    .RegisterAnalyzer(new RoslynApiAnalyzer())
    .RegisterVersionGenerator(new SemanticVersionGenerator());

// Analyze your API project
var (breakingChanges, newVersion) = await engine.AnalyzeAndVersionAsync("./path/to/your/project");

Console.WriteLine($"Suggested version: {newVersion}");
Console.WriteLine($"Breaking changes found: {breakingChanges.Count}");

ASP.NET Core Integration

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// Add ApiVersionAuto services
builder.Services.AddApiVersionAuto();

var app = builder.Build();

// Map ApiVersionAuto endpoints
app.MapApiVersionAuto();

app.Run();

🎯 Usage Examples

1. Basic API Analysis

using ApiVersionAuto;

var analyzer = new AnalyzerEngine()
    .RegisterAnalyzer(new RoslynApiAnalyzer())
    .RegisterVersionGenerator(new SemanticVersionGenerator());

var (breakingChanges, suggestedVersion) = await analyzer.AnalyzeAndVersionAsync("./MyApi");

if (breakingChanges.Count > 0)
{
    Console.WriteLine($"⚠️ Breaking changes detected! Suggested version: {suggestedVersion}");
    foreach (var change in breakingChanges)
    {
        Console.WriteLine($"- {change}");
    }
}

2. Custom Analyzer Configuration

var engine = new AnalyzerEngine()
    .RegisterAnalyzer(new RoslynApiAnalyzer())
    .RegisterAnalyzer(new CustomApiAnalyzer()) // Your custom analyzer
    .RegisterVersionGenerator(new SemanticVersionGenerator())
    .RegisterVersionGenerator(new CustomVersionGenerator()); // Your custom generator

3. Attribute-Based Control

[ApiVersion("2.0")]
[ExcludeFromVersionAnalysis("Internal API")]
public class UsersController : ControllerBase
{
    [NonBreakingChange("Adding optional parameter")]
    public IActionResult GetUsers(string? filter = null)
    {
        // This change won't trigger a version bump
    }
    
    [IntentionalBreakingChange("Removing deprecated endpoint")]
    public IActionResult GetUser(int id)
    {
        // This will be marked as an intentional breaking change
    }
}

4. Changelog Generation

using ApiVersionAuto.Generators;

var generator = new ChangelogGenerator();
var versionInfo = new VersionInfo
{
    CurrentVersion = "1.0.0",
    SuggestedVersion = "2.0.0",
    ChangeType = VersionChangeType.Major
};

var breakingChanges = new List<BreakingChange>
{
    new BreakingChange
    {
        Type = BreakingChangeType.MethodSignatureChanged,
        Severity = BreakingChangeSeverity.High,
        Description = "GetUser method signature changed",
        AffectedApi = "GET /api/users/{id}"
    }
};

var changelog = generator.GenerateMarkdownChangelog(versionInfo, breakingChanges);
Console.WriteLine(changelog);

🔧 Configuration

ASP.NET Core Integration

// Add services with custom configuration
builder.Services.AddApiVersionAuto(engine =>
{
    engine.RegisterAnalyzer(new RoslynApiAnalyzer());
    engine.RegisterVersionGenerator(new SemanticVersionGenerator());
});

// Map endpoints with custom path
app.MapApiVersionAuto("/api/versioning");

Available Endpoints

• GET /api/version/analyze?projectPath={path} - Analyze API version
• POST /api/version/changelog - Generate changelog
• GET /api/version/summary?projectPath={path} - Get breaking changes summary

🎛️ Attributes

ApiVersionAttribute

Manually specify API version for controllers or actions.

[ApiVersion("2.0")]
public class UsersController : ControllerBase
{
    // This controller is explicitly versioned
}

ExcludeFromVersionAnalysisAttribute

Exclude controllers or actions from version analysis.

[ExcludeFromVersionAnalysis("Internal API")]
public class InternalController : ControllerBase
{
    // This controller won't be analyzed
}

NonBreakingChangeAttribute

Mark changes as non-breaking.

[NonBreakingChange("Adding optional parameter")]
public IActionResult GetUsers(string? filter = null)
{
    // This change won't trigger a version bump
}

ForceVersionChangeAttribute

Force a specific version change type.

[ForceVersionChange(VersionChangeType.Major, "Major refactoring")]
public class RefactoredController : ControllerBase
{
    // This will force a major version change
}

IntentionalBreakingChangeAttribute

Mark breaking changes as intentional.

[IntentionalBreakingChange("Removing deprecated endpoint")]
public IActionResult GetUser(int id)
{
    // This will be marked as an intentional breaking change
}

📊 Breaking Change Detection

ApiVersionAuto detects the following types of breaking changes:

Method Signature Changes

• Parameter type changes
• Parameter order changes
• Return type changes
• Method removal

Route Changes

• Route pattern changes
• HTTP method changes
• Route parameter changes

Model Changes

• Property type changes
• Property removal
• Model structure changes

Security Changes

• Authentication requirements
• Authorization requirements
• Security header changes

🔍 Severity Levels

• Critical: Will definitely break existing clients
• High: Likely to break existing clients
• Medium: May break some clients
• Low: Unlikely to break clients

📝 Changelog Generation

ApiVersionAuto generates comprehensive changelogs including:

• Breaking changes with severity levels
• Migration guides for each change
• Affected API endpoints
• File locations and line numbers
• Detailed explanations

🛠️ Customization

Custom Analyzers

public class CustomApiAnalyzer : IApiAnalyzer
{
    public string Name => "CustomAnalyzer";
    
    public async Task<IList<string>> AnalyzeAsync(string projectPath)
    {
        // Your custom analysis logic
        return new List<string>();
    }
}

Custom Version Generators

public class CustomVersionGenerator : IVersionGenerator
{
    public string Name => "CustomGenerator";
    
    public async Task<string> GenerateVersionAsync(string projectPath, IList<string> breakingChanges)
    {
        // Your custom version generation logic
        return "2.0.0";
    }
}

🧪 Testing

[Test]
public async Task TestApiVersionAnalysis()
{
    var engine = new AnalyzerEngine()
        .RegisterAnalyzer(new RoslynApiAnalyzer())
        .RegisterVersionGenerator(new SemanticVersionGenerator());
    
    var (breakingChanges, newVersion) = await engine.AnalyzeAndVersionAsync("./test-project");
    
    Assert.IsNotNull(newVersion);
    Assert.IsNotNull(breakingChanges);
}

📈 Performance

• Fast Analysis: Roslyn-based analysis for quick results
• Incremental: Only analyzes changed files
• Caching: Caches analysis results for better performance
• Parallel Processing: Analyzes multiple files concurrently

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 📧 Email: support@apiversionauto.com
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Wiki

🚀 Roadmap

• Visual Studio Extension
• CI/CD Integration
• Custom Rule Engine
• Performance Benchmarking
• Memory Usage Analysis
• Async/Await Analysis
• OpenAPI/Swagger Integration
• Git Integration for Change Tracking

Made with ❤️ for the .NET community