Class RestfulSwaggerOptions

Namespace

Codebelt.Extensions.Swashbuckle.AspNetCore

Assembly

Codebelt.Extensions.Swashbuckle.AspNetCore.dll

Provides programmatic configuration for the AddRestfulSwagger(IServiceCollection, Action<RestfulSwaggerOptions>) method.

public class RestfulSwaggerOptions : IValidatableParameterObject, IParameterObject

Inheritance

object

RestfulSwaggerOptions

Implements

IValidatableParameterObject

IParameterObject

Examples

Customize Swagger generation and UI settings for a RESTful API. The RestfulSwaggerOptions type bundles all configuration aspects: OpenAPI document metadata, XML documentation loading, and schema generation options. This example shows how to configure core settings:

using System;
using Codebelt.Extensions.Swashbuckle.AspNetCore;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

namespace MySwaggerExample;

public class Program
{
    public static void Main(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        builder.Services.AddControllers();
        builder.Services.AddEndpointsApiExplorer();

        // Configure RestfulSwaggerOptions with customized settings
        builder.Services.AddRestfulSwagger(rawOptions =>
        {
            // Explicitly declare RestfulSwaggerOptions type
            RestfulSwaggerOptions options = rawOptions;

            // Configure document metadata through OpenApiInfo property
            options.OpenApiInfo.Title = "My REST API";
            options.OpenApiInfo.Description = "A sample API documentation";
            options.OpenApiInfo.Contact.Name = "API Support";

            // Enable XML documentation comments
            options.XmlDocumentations.AddByType<Program>();

            // Configure Swagger generation through Settings
            options.Settings.UseAllOfToExtendReferenceSchemas();
        });

        var app = builder.Build();

        if (string.Equals(app.Environment.EnvironmentName, "Development", StringComparison.OrdinalIgnoreCase))
        {
            app.UseSwagger();
            app.UseSwaggerUI();
        }

        app.MapControllers();
        app.Run();
    }
}

Constructors

RestfulSwaggerOptions()

Initializes a new instance of the RestfulSwaggerOptions class.

public RestfulSwaggerOptions()

Remarks

The following table shows the initial property values for an instance of RestfulSwaggerOptions.

Property	Initial Value
XmlDocumentations	new List<XPathDocument>();
OpenApiInfo	new();
IncludeControllerXmlComments	false

Properties

IncludeControllerXmlComments

Flag to indicate if controller XML comments (i.e. summary) should be used to assign Tag descriptions. Don't set this flag if you're customizing the default tag for operations via TagActionsBy.

public bool IncludeControllerXmlComments { get; set; }

Property Value

bool

true if controller XML comments (i.e. summary) should be used to assign Tag descriptions; otherwise, false.

JsonSerializerOptionsFactory

Gets or sets the function delegate that will resolve a JsonSerializerOptions instance.

public Func<IServiceProvider, JsonSerializerOptions> JsonSerializerOptionsFactory { get; set; }

Property Value

Func<IServiceProvider, JsonSerializerOptions>

The function delegate that will resolve a JsonSerializerOptions instance.

Remarks

The Swagger team decided to opt-in full hearted to System.Text.Json using the MVC variant of JsonOption to retrieve an instance of JsonSerializerOptions. Weird design choice IMO; leave it to the implementor to decide which configured instance of JsonSerializerOptions to use and avoid redundant configuration that may or may not be a mismatch. More info: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/1269

OpenApiInfo

Gets or sets the open API information that may be configured.

public OpenApiInfoOptions OpenApiInfo { get; set; }

Property Value

OpenApiInfoOptions

The open API information that may be configured.

Settings

Gets or sets the SwaggerGenOptions used to configure Swagger.

public SwaggerGenOptions Settings { get; set; }

Property Value

SwaggerGenOptions

The SwaggerGenOptions used to configure Swagger.

XmlDocumentations

Gets or sets a list of XML documentations to apply to a Swagger document.

public IList<XPathDocument> XmlDocumentations { get; set; }

Property Value

IList<XPathDocument>

The list of XML documentations to apply to a Swagger document.

Methods

ValidateOptions()

Determines whether the public read-write properties of this instance are in a valid state.

public void ValidateOptions()

Remarks

This method is expected to throw exceptions when one or more conditions fails to be in a valid state.

Exceptions

InvalidOperationException

OpenApiInfo cannot be null - or - XmlDocumentations cannot be null - or - Settings cannot be null.