Skip to main content

RA.Utilities.OpenApi

· 3 min read
Redon Alla
Redon Alla
.NET, React, Angular Developer

NuGet version

This release of RA.Utilities.OpenApi provides a robust set of tools to enhance and customize OpenAPI (Swagger) documentation in ASP.NET Core applications. It automates common modifications to your generated OpenAPI specification, reducing boilerplate and enforcing consistency.

✨ Key Features​

  • DocumentInfoTransformer: Populates the top-level info object of your OpenAPI document (title, version, description, etc.) directly from your appsettings.json configuration, allowing you to update documentation details without code changes.

  • BearerSecuritySchemeTransformer: Automatically adds a "Bearer" security scheme to your OpenAPI document when JWT authentication is detected, enabling the "Authorize" button in Swagger UI for testing protected endpoints.

  • HeadersParameterTransformer: Adds common, configurable headers (like x-request-id) to every API operation, ensuring consistent documentation for tracing and correlation in distributed systems.

  • ResponsesDocumentTransformer: Automatically adds standardized OpenAPI responses for common HTTP status codes (400, 404, 409, 500), using schema models from RA.Utilities.Api.Results to ensure your error contracts are clearly documented.

  • Simplified Setup: Includes an AddDefaultsDocumentTransformer() extension method to register the most common transformers (DocumentInfo, BearerSecurityScheme, and HeadersParameter) with a single line of code.

  • Configuration-Driven: All transformers are configurable via appsettings.json using strongly-typed settings classes (OpenApiInfoSettings, HeadersParameterSettings), keeping your application code clean and focused.

🚀 Getting Started​

  1. Configure Settings: Add OpenApiInfoSettings and OpenApiHeaders sections to your appsettings.json.
  2. Register Services: In Program.cs, configure the settings classes: 
    builder.Services.Configure<OpenApiInfoSettings>(builder.Configuration.GetSection(OpenApiInfoSettings.AppSettingsKey));
    builder.Services.Configure<HeadersParameterSettings>(builder.Configuration.GetSection("OpenApiHeaders"));
  3. Add Transformers: Use the extension methods to register the transformers: 
    builder.Services.AddOpenApi()
        .AddDefaultsDocumentTransformer(); // Adds Info, Bearer, and Headers transformers

    // Register other transformers individually
    builder.Services.AddOpenApiDocumentTransformer<ResponsesDocumentTransformer>();
  4. Map Endpoints: Finally, map the OpenAPI endpoints in your request pipeline: 
    app.MapOpenApi();

✨ New Features & Improvements​

  • Added SuccessResponse Helpers: Introduced a new static SuccessResponse class with helper methods (Ok, Created, NoContent, etc.) to simplify the creation of standardized, successful API responses. This complements the existing error response models and promotes a consistent response structure across the entire API.
  • Improved README Documentation:
    • Added a new section to the README.md detailing the usage of the new SuccessResponse helpers.
    • Updated the endpoint example for using the Result<T> type to demonstrate a cleaner, more powerful pattern using both SuccessResponse.Ok() for success cases and ErrorResultResponse.Result for failure cases.

📝 Notes​

The main goal of this update is to make API endpoint logic cleaner and more readable. By providing dedicated helpers for both success and failure responses, developers can write more expressive and maintainable code while ensuring a consistent API contract for consumers.