SH.Framework.OpenApi.Implementation 1.0.1

SH.Framework.OpenApi.Implementation

A comprehensive implementation layer for OpenAPI integration in ASP.NET Core projects. This package provides extension methods and helpers for customizing OpenAPI schema generation, including friendly schema reference IDs and configuration registration. It extends the default OpenAPI experience with practical utilities for schema naming and configuration.

🚀 Features

• 🔗 Extension Methods: Easily register OpenAPI configuration in your DI container
• 🆔 Friendly Schema Reference IDs: Custom logic for readable and unique schema IDs
• 🔧 Flexible Configuration: Customize OpenAPI options for your project
• 📦 .NET 10 Support: Modern .NET compatibility
• 🛡️ Type Safety: Strongly-typed extension points
• 🎯 Clean Architecture: Promotes maintainable and scalable API documentation

📦 Installation

dotnet add package SH.Framework.OpenApi.Implementation

Note: This package automatically includes required dependencies for OpenAPI integration.

🛠️ Quick Start

1. Register OpenAPI Configuration

using SH.Framework.Library.OpenApi.Implementation;

var builder = WebApplication.CreateBuilder(args);

// Register OpenAPI configuration
builder.Services.AddOpenApiConfiguration();

var app = builder.Build();

2. Customize Schema Reference IDs

The package provides a helper for generating friendly schema reference IDs:

using SH.Framework.Library.OpenApi.Implementation;

string schemaId = OpenApiExtensions.CreateFriendlyId(typeof(List<string>));
// Output: ListOfString

3. Use in ASP.NET Core Projects

Integrate with your API project for improved OpenAPI documentation:

public static class RegisterOpenApiConfiguration
{
    public static IServiceCollection AddOpenApiConfiguration(this IServiceCollection services) {
        services.AddOpenApi(options =>
        {
            options.CreateSchemaReferenceId = context =>
            {
                return OpenApiExtensions.CreateFriendlyId(context.Type);
            };
        });
        return services;
    }
}

🏗️ Architecture Components

Friendly Schema Reference ID

Generates readable and unique schema IDs for OpenAPI documents:

public static string CreateFriendlyId(Type type)
{
    if (type.IsArray)
        return $"{CreateFriendlyId(type.GetElementType()!)}Array";
    if (type.IsGenericType)
    {
        var nameBuilder = new StringBuilder();
        var cleanName = type.Name.Split('`')[0];
        nameBuilder.Append(cleanName);
        nameBuilder.Append("Of");
        var args = type.GetGenericArguments();
        for (int i = 0; i < args.Length; i++)
            nameBuilder.Append(CreateFriendlyId(args[i]));
        return nameBuilder.ToString();
    }
    if (type.IsNested && type.DeclaringType != null)
        return $"{CreateFriendlyId(type.DeclaringType)}{type.Name}";
    var id = type.Name;
    return id.Replace("[]", "Array").Replace("[", "").Replace("]", "").Replace(",", "").Replace("+", "");
}

Extension Registration

public static IServiceCollection AddOpenApiConfiguration(this IServiceCollection services)
{
    services.AddOpenApi(options =>
    {
        options.CreateSchemaReferenceId = context =>
        {
            return OpenApiExtensions.CreateFriendlyId(context.Type);
        };
    });
    return services;
}

🔧 Advanced Usage

Custom Schema Naming

You can extend or override the schema ID generation logic for your own types:

options.CreateSchemaReferenceId = context =>
{
    // Custom logic
    return MyCustomSchemaIdGenerator(context.Type);
};

Integration with Other OpenAPI Tools

This package is compatible with other OpenAPI/Swagger tools and can be used to enhance schema documentation and naming conventions.

📊 Response Patterns

OpenAPI schema IDs generated by this package will be readable and unique, improving the clarity of your API documentation.

🎯 Best Practices

1. Use friendly schema IDs for better documentation
2. Register OpenAPI configuration early in your DI setup
3. Customize options as needed for your API
4. Leverage extension methods to keep your startup code clean
5. Follow clean architecture principles for scalable API projects

🔗 Dependencies

• Microsoft.AspNetCore.OpenApi: OpenAPI integration for ASP.NET Core
• Microsoft.Extensions.DependencyInjection: DI support
• .NET 10.0: Target framework

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

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

🏢 Company

Strawhats Company
Created by Muharrem Kaçkın

⭐ If you find this library helpful, please consider giving it a star on GitHub!