A new NuGet has been born

Whenever a new Web/REST API is created, there are always some “boilerplate” configurations and setups to do. And always takes tedious time to do those configurations.

This NuGet library is the first attempt to gather the most common configuration in one place and provide a simple API to do so.

Presenting MasterZdran Rest API Extensions, an open-source dotnet NuGet library targeted to netstandard 2.0.

What does this version include?

API PAGING

[HttpGet(Name = "GetWeatherForecast")]
public IEnumerable<WeatherForecast> Get([FromQuery] ApiPaging paging)
{
    return Enumerable.Range(paging.FirstRecord, paging.PageSize).Select(index => new WeatherForecast
    {
        Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
        TemperatureC = Random.Shared.Next(-20, 55),
        Summary = s_summaries[index]
    })
    .ToArray();
}

This model is a set of common properties usually associated with GET methods with pagination.

The DEFAULT PAGE SIZE is 20, and the MAX PAGE SIZE is 50. If the value is negative or greater than MAX PAGE SIZE, by default return DEFAULT PAGE SIZE.
The PAGE NUMBER is a based index. If the value is negative, by default return page 0.
‘ORDERED FIELD’, is the field the client wants to results ordered, and ‘ORDERED BY’ should be set also.
None of the fields are mandatory.

HTTP Media Types Constants (HttpMediaTypes)

        [HttpGet(Name = "GetWeatherForecast")]
        [ProducesResponseType(StatusCodes.Status200OK)]
        [Produces(HttpMediaTypes.ApplicationJson)] // // <<--- HERE 
        public IEnumerable<WeatherForecast> Get([FromQuery] ApiPaging paging)
        {
            // ...
        }

This model has a set of constants of HTTP media type usually associated with API responses and requests.

Generic API (GET) Response (ResponseType<T>)

[HttpGet(Name = "GetWeatherForecast")]
[ProducesResponseType(StatusCodes.Status200OK)]
[Produces(HttpMediaTypes.ApplicationJson)]
public ResponseType<WeatherForecast> Get([FromQuery] ApiPaging paging) // <<--- HERE
{
    var response = new ResponseType<WeatherForecast>(); // <<--- HERE 

    response.TotalNumberOfRecords = s_summaries.Length;
    response.Results = Enumerable
            .Range(paging.FirstRecord, paging.PageSize)
            .Select(index => new WeatherForecast
    {
        Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
        TemperatureC = Random.Shared.Next(-20, 55),
        Summary = s_summaries[index]
    })
    .ToArray();

    return response;
}

This generic response type has a compound response of paginated requests and includes properties to return an errors list if any.

Swashbuckle Extensions

This is the first attempt to simplify the “basic” configuration of Swashbuckle Swagger in the projects. Most projects are pretty straightforward, with the same configurations. Instead of copying and pasting those configurations, this library offers a simple interface and expects the appsettings to be properly set for the flow itself.

It also offers the flexibility to create new “configurations” while keeping the appsettings structure.

It has extension methods to “automatically” configure OAuth2 Flows (Implicit, Password, Client Credentials, and Authorization Code) and API Key, by using the information provided in the appsettings structure.

example:

// Get Options from appsettings
SwaggerExtensionsOptions swaggerOptions = new SwaggerExtensionsOptions(); // <<--- HERE
builder.Configuration
.GetSection(SwaggerExtensionsConstants.SwaggerOptionsConfiguration)
.Bind(swaggerOptions); // <<--- HERE

// Add  Authentication to the API. Azure AD for example.
builder.Services
.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
.AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));

// ... Other configurations

// Register the 'automatic' Swagger generator configurations.
builder.Services.AddCustomSwaggerGenerator(swaggerOptions); // <<--- HERE

// ... Other configurations

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseCustomSwagger(swaggerOptions);
}

// ... Other configurations

For more usage, take a look at the GitHub repository.

Conclusion

This NuGet library simplifies the tedious task of “boilerplate” configuration of Swashbuckle Swagger and also provides some useful models to be used in the controllers.

The project is open-source, under MIT License, so you are all invited to contribute. I accept merge/pull requests. 😇