DarkruneDK.Swagger 1.0.1

DarkruneDK's Swagger Extensions

This is a small library that provides some extensions for Swagger in .NET 10.0 projects. It includes a way to mark certain enums so they are displayed by Swagger as their string values instead of their integer values.

Both the integer and string values of the enum will still work, but Swagger will display the string value in the dropdowns.

How do I use it?

In order to enable this functionality, you need to add this package to your project.

After that you need to add the following line to your Program.cs file after your services.AddControllers() like this:

services.AddControllers().AddJsonOptions(options =>
{
    options.JsonSerializerOptions.Converters.Add(new EnumToStringConverter());
});

Now you can mark your enums with the [EnumToString] attribute like this:

[EnumToString]
public enum CustomerType
{
    Unknown = 0,
    Individual = 1,
}

This is all it takes to make the change to Swagger. Now when you look at the Swagger UI, you will see the string values of the enum instead of the integer values.

Filters

The package also includes two filters which can help with documentation, as it will be created at runtime and is in-code. This also means you don't need to generate large xml files for the documenation, which can save some space.

These two filters are in the package to help with that:

• SwaggerDescriptionOperationFilter - This filter enables the use of SwaggerDescriptionAttribute on the method level, which allows you to add a description to the method in the Swagger UI.
• SwaggerDescriptionDocumentFilter - This filter enables the use of SwaggerDescriptionAttribute on the controller level, which allows you to add a description to the controller in the Swagger UI.

The way to enable the filters is to extend the AddSwaggerGen method in your Program.cs file like this:

services.AddSwaggerGen(options =>
{
    options.OperationFilter<SwaggerDescriptionOperationFilter>();
    options.DocumentFilter<SwaggerDescriptionDocumentFilter>();
});

This will enable the filters and allow you to use the SwaggerDescriptionAttribute on your methods and controllers.

The attribute can be used like this:

[SwaggerDescription("Test controller.")]
[Route("[controller]")]
[ApiController]
public class TestController : ControllerBase
{
    [SwaggerDescription("Gets the chosen customer.", "Gets customer.")]
    [Route("GetCustomer/{customer}")]
    [HttpGet]
    public IActionResult GetCustomer(CustomerType customer)
    {
        return Ok();
    }
}

This will display the description in the Swagger UI for both the controller and the method.

NOTE: The summary is ignored at controller level documentation, as there exist no summary field for controllers in the Swagger UI. The summary is only used for methods.