ApiDocSyncer 1.0.0

ApiDocSyncer

🔄 Automatically sync Swagger/OpenAPI documentation with markdown files or Postman collections, ensuring API docs are always up-to-date and reducing manual documentation drift.

📋 Overview

ApiDocSyncer is a powerful .NET library that automatically synchronizes your OpenAPI/Swagger documentation with multiple formats including Markdown and Postman collections. It's designed to keep your API documentation always accurate and up-to-date, eliminating the manual effort of maintaining documentation.

✨ Key Features

• 🔄 Auto-Sync - Automatically updates docs when API changes
• 📝 Multiple Formats - Markdown, Postman collections, and extensible
• 📊 Changelog Generation - Tracks and documents API changes
• 🔍 Diff Reports - Shows what changed in documentation
• 💾 Backup System - Safely backs up previous documentation
• ⚡ High Performance - Fast processing with minimal overhead
• 🔧 Easy Integration - Simple ASP.NET Core integration
• 🛡️ Validation - Validates OpenAPI specifications
• 📈 Extensible - Add custom format providers

🚀 Quick Start

Installation

dotnet add package ApiDocSyncer

Basic Usage

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

// Add API documentation syncer
builder.Services.AddApiDocSyncer(options =>
{
    options.OutputDirectory = "./docs";
    options.GenerateChangelog = true;
    options.GenerateDiffReport = true;
    options.CreateBackup = true;
});

var app = builder.Build();

// Get the syncer service
var docSyncer = app.Services.GetRequiredService<DocSyncEngine>();

// Sync documentation from OpenAPI JSON
var openApiJson = await File.ReadAllTextAsync("./swagger.json");
var result = await docSyncer.SyncAsync(openApiJson);

if (result.IsSuccess)
{
    Console.WriteLine($"Generated {result.FilesGenerated} files");
}

🎯 Usage Examples

1. Basic Synchronization

// Simple setup with defaults
builder.Services.AddApiDocSyncer();

// Use the syncer
var docSyncer = app.Services.GetRequiredService<DocSyncEngine>();
var result = await docSyncer.SyncAsync(openApiJson);

2. Custom Configuration

builder.Services.AddApiDocSyncer(options =>
{
    options.OutputDirectory = "./api-docs";
    options.GenerateChangelog = true;
    options.GenerateDiffReport = true;
    options.CreateBackup = true;
    options.MaxBackupFiles = 5;
    options.IncludeExamples = true;
    options.IncludeAuthInfo = true;
    options.DocumentationTitle = "My API Documentation";
    options.FileNamePattern = "api-docs-{timestamp}";
});

3. Custom Format Provider

public class CustomFormatProvider : IFormatProvider
{
    public string Format => "custom";
    public string FileExtension => "txt";

    public async Task<DocSyncResult> ExportAsync(string openApiJson, string outputPath, DocSyncOptions options)
    {
        // Your custom implementation
        await File.WriteAllTextAsync(outputPath, "Custom format content");
        
        return new DocSyncResult
        {
            IsSuccess = true,
            FilesGenerated = 1,
            GeneratedFiles = { outputPath }
        };
    }

    public Task<bool> ValidateAsync(string openApiJson) => Task.FromResult(true);
    public string[] GetSupportedFeatures() => new[] { "custom" };
}

// Register custom provider
builder.Services.AddFormatProvider<CustomFormatProvider>();

4. CI/CD Integration

// In your CI/CD pipeline
var docSyncer = serviceProvider.GetRequiredService<DocSyncEngine>();

// Sync documentation
var result = await docSyncer.SyncAsync(openApiJson);

if (!result.IsSuccess)
{
    throw new Exception($"Documentation sync failed: {result.ErrorMessage}");
}

// Commit changes to repository
if (result.FilesGenerated > 0)
{
    // Git operations to commit updated docs
}

🔧 Configuration Options

DocSyncOptions

📊 Supported Formats

Markdown Format

• ✅ Complete endpoint documentation
• ✅ Request/response schemas
• ✅ Authentication information
• ✅ Examples and descriptions
• ✅ Data models and properties
• ✅ Custom styling support

Postman Collection

• ✅ Full Postman collection export
• ✅ Request parameters and headers
• ✅ Authentication setup
• ✅ Environment variables
• ✅ Response examples
• ✅ Folder organization

Custom Formats

• ✅ Extensible provider system
• ✅ Custom validation
• ✅ Feature support declaration
• ✅ Flexible output formats

🛠️ Advanced Usage

Custom Format Provider

public class HtmlFormatProvider : IFormatProvider
{
    public string Format => "html";
    public string FileExtension => "html";

    public async Task<DocSyncResult> ExportAsync(string openApiJson, string outputPath, DocSyncOptions options)
    {
        // Parse OpenAPI JSON
        var doc = JsonDocument.Parse(openApiJson);
        
        // Generate HTML content
        var html = GenerateHtmlContent(doc.RootElement, options);
        
        // Write to file
        await File.WriteAllTextAsync(outputPath, html);
        
        return new DocSyncResult
        {
            IsSuccess = true,
            FilesGenerated = 1,
            GeneratedFiles = { outputPath }
        };
    }

    public Task<bool> ValidateAsync(string openApiJson)
    {
        try
        {
            JsonDocument.Parse(openApiJson);
            return Task.FromResult(true);
        }
        catch
        {
            return Task.FromResult(false);
        }
    }

    public string[] GetSupportedFeatures() => new[] { "html", "styling", "interactive" };
}

Integration with ASP.NET Core

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

// Add API documentation syncer
builder.Services.AddApiDocSyncer(options =>
{
    options.OutputDirectory = "./docs";
    options.GenerateChangelog = true;
    options.GenerateDiffReport = true;
});

var app = builder.Build();

// Add endpoint to trigger documentation sync
app.MapPost("/api/docs/sync", async (DocSyncEngine docSyncer, [FromBody] string openApiJson) =>
{
    var result = await docSyncer.SyncAsync(openApiJson);
    return Results.Ok(result);
});

app.Run();

CI/CD Integration

# GitHub Actions example
name: Sync API Documentation

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  sync-docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup .NET
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: '8.0.x'
    
    - name: Build and sync docs
      run: |
        dotnet build
        dotnet run --project ApiDocSyncer -- sync ./swagger.json
    
    - name: Commit changes
      run: |
        git config --local user.email "action@github.com"
        git config --local user.name "GitHub Action"
        git add docs/
        git commit -m "Update API documentation" || exit 0
        git push

🧪 Testing

Unit Testing

[Test]
public async Task TestMarkdownGeneration()
{
    // Arrange
    var options = new DocSyncOptions();
    var provider = new MarkdownFormatProvider();
    var openApiJson = File.ReadAllText("test-openapi.json");
    
    // Act
    var result = await provider.ExportAsync(openApiJson, "test-output.md", options);
    
    // Assert
    Assert.IsTrue(result.IsSuccess);
    Assert.AreEqual(1, result.FilesGenerated);
    Assert.IsTrue(File.Exists("test-output.md"));
}

Integration Testing

[Test]
public async Task TestDocSyncEngine()
{
    // Arrange
    var services = new ServiceCollection();
    services.AddApiDocSyncer();
    var serviceProvider = services.BuildServiceProvider();
    
    var docSyncer = serviceProvider.GetRequiredService<DocSyncEngine>();
    var openApiJson = File.ReadAllText("test-openapi.json");
    
    // Act
    var result = await docSyncer.SyncAsync(openApiJson);
    
    // Assert
    Assert.IsTrue(result.IsSuccess);
    Assert.Greater(result.FilesGenerated, 0);
    Assert.Greater(result.EndpointsProcessed, 0);
}

📈 Performance

Benchmarks

• Small API (10 endpoints): ~50ms processing time
• Medium API (50 endpoints): ~200ms processing time
• Large API (200 endpoints): ~800ms processing time
• Memory usage: ~10MB for typical APIs

Optimization Tips

• Use IncludeDeprecated = false for faster processing
• Disable GenerateDiffReport if not needed
• Set appropriate MaxBackupFiles to limit disk usage
• Use custom format providers for specific needs

🔒 Security Considerations

• Input validation: Always validate OpenAPI specifications
• File permissions: Ensure proper file system permissions
• Backup security: Secure backup directories
• Custom providers: Validate custom format provider implementations

🤝 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: asajjad308@gmail.com

🚀 Roadmap

• HTML format provider
• PDF format provider
• Real-time sync with file watchers
• Webhook integration
• Advanced diff visualization
• Custom template system
• Multi-language support
• Performance optimizations

Made with ❤️ for the .NET community