Configure Swagger

The document generation configuration is done in the Startup class of your API, within the ConfigureServices(IServiceCollection services) method. A call to the extension method AddSwaggerGen(Action<SwaggerGenOptions> setupAction) is made passing an action to generate the documentation options.

Each call to AddSwaggerGen() will generate a new document. The parameters passed will be used to configure the rules for document generation. The output of a document generation process is a simple JSON file. By default the file(spec) will be available on /swagger/versionName/swagger.json.

Example:

Startup.cs (Register doc generation)

public class Startup
{
    public IConfiguration Configuration { get; }
    private readonly IHostingEnvironment _hostingEnv;

    public Startup(IHostingEnvironment env, IConfiguration configuration)
    {
        _hostingEnv = env;
        Configuration = configuration;
    }

    public void ConfigureServices(IServiceCollection services)
    {
        services
            .AddMvcCore()
            .AddApiExplorer()
            ... Omit for brevity ...;

        services
            .AddSwaggerGen(c =>
            {
                //defines the doc version
                c.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "API",
                    Description = "APIs endpoints"
                });

                //will generate models containing only the class name, ignoring the namespace
                c.CustomSchemaIds(type => type.FriendlyId(false));

                //Enum will be generated as strings
                c.DescribeAllEnumsAsStrings();

                //Will load the comments provided in the code using / / / , the build will generate the xml file in the output folder.
                // Make sure the project file contains the attribute <GenerateDocumentationFile>true</GenerateDocumentationFile>
                c.IncludeXmlComments($"{AppContext.BaseDirectory}{Path.DirectorySeparatorChar}{_hostingEnv.ApplicationName}.xml");

                // Show only operations where route starts with v1
                c.DocumentFilter<VersionPathFilter>("/v1");

                // Include DataAnnotation attributes on Controller Action parameters as Swagger validation rules (e.g required, pattern, ..)
                // Enforce parameters provided in the path to be required
                // Use [ValidateModelState] on Actions to actually validate it in C# as well!
                c.OperationFilter<GeneratePathParamsValidationFilter>();
            });
    }
}

The snippet above demonstrates the usage of .AddSwaggerGen() to register the document generation. The output of this snipped will generate a document found on the path /swagger/v1/swagger.json.

Configure Swagger#

Configure Swagger