Skip to main content

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.


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)
... Omit for brevity ...;

.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

//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>

// Show only operations where route starts with 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!

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.