Asp.Net Web Api Configuring Swagger Ui And Annotations Complete Guide

1. How do I install Swagger in an ASP.NET Web API project?

To install Swagger (OpenAPI Specification) in an ASP.NET Web API project, you can use the Swashbuckle.AspNetCore NuGet package. Here’s how to do it via the NuGet Package Manager Console:

Install-Package Swashbuckle.AspNetCore

After installation, you need to configure Swagger in the Startup class:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    // Register Swagger service.
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();

        // Enable middleware to serve generated Swagger as a JSON endpoint.
        app.UseSwagger();

        // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        });
    }

    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

2. How can I customize the Swagger UI look and feel?

You can customize the Swagger UI by modifying the Swagger UI options within the UseSwaggerUI method:

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.DocumentTitle = "My API Documentation";
    c.DocExpansion(DocExpansion.List);
    c.InjectStylesheet("/swagger-ui/custom.css");
});

Additionally, you can create custom HTML views and stylesheets by creating your own index.html file in the wwwroot directory and setting InjectStylesheet/InjectJavascript to point to it.

3. How do I add XML comments to Swagger documentation?

To enrich your Swagger documentation with XML comments, you need to generate XML documentation files from the API source code. Add the following XML documentation settings to your .csproj file:

<PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Then, configure Swagger to use these XML files in the Startup class:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo() { Title = "My API", Version = "v1" });

    // Set the comments path for the Swagger JSON and UI.
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

4. How can I describe response models in Swagger UI?

To describe response models in Swagger UI, you can use the [ProducesResponseType] attribute on your action methods. This attribute specifies the status code and the type of response.

Example:

[HttpGet]
[ProducesResponseType(StatusCodes.Status200OK, Type = typeof(IEnumerable<Product>))]
public IActionResult GetProducts()
{
    var products = // fetch products;
    return Ok(products);
}

5. How do I document the parameters of actions in Swagger UI?

You can use the [FromQuery], [FromBody], and [FromRoute] attributes to indicate how parameters are passed in the HTTP request, and [Obsolete] for marking deprecated parameters. Additionally, data annotations can be used to provide more information about parameters:

[HttpGet]
public IHttpActionResult Get([FromQuery][Required] int id)
{
    // action implementation
}

6. Can I document exceptions in Swagger UI?

You can document exceptions with the [ProducesResponseType] attribute, specifying the status code and error model.

Example:

[HttpGet("{id}")]
[ProducesResponseType(StatusCodes.Status200OK, Type = typeof(Product))]
[ProducesResponseType(StatusCodes.Status404NotFound, Type = typeofProblemDetails))]
public IActionResult GetProduct(int id)
{
    var product = // fetch product;
    if (product == null) return NotFound(new ProblemDetails { Title = "Product not found", Status = 404 });

    return Ok(product);
}

7. How do I add authentication to Swagger UI?

To add authentication in Swagger UI, you need to configure the AddSwaggerGen and AddSwaggerUI methods for security schemes such as OAuth2 or Basic Authentication.

Example for OAuth2:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo() { Title = "My API", Version = "v1" });

    c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
    {
        Description = "OAuth2 Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\"",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey
    });

    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "oauth2"
                }
            },
            new[] { "readAccess", "writeAccess" }
        }
    });
});

app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    c.OAuthClientId("your-client-id");
    c.OAuthAppName("MyApplication");
});

8. How can versioning be handled in Swagger UI?

To handle API versioning with Swagger, you need to configure versioning in your application and create separate Swagger documents for each version.

Example:

services.AddApiVersioning(opt =>
{
    opt.DefaultApiVersion = new ApiVersion(1, 0);
    opt.AssumeDefaultVersionWhenUnspecified = true;
});

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "API V1", Version = "v1" });
    c.SwaggerDoc("v2", new OpenApiInfo { Title = "API V2", Version = "v2" });

    c.DocInclusionPredicate((docName, description) =>
    {
        if (!description.TryGetMethodInfo(out MethodInfo methodInfo)) return false;

        var versions = methodInfo.DeclaringType.GetCustomAttributes(true).OfType<ApiVersionAttribute>().SelectMany(attr => attr.Versions);
        return versions.Any(v => $"v{v}" == docName);
    });
});

9. How do I exclude certain controllers or actions from Swagger UI documentation?

To exclude controllers or actions from Swagger documentation, you can use the [ApiExplorerSettings(IgnoreApi = true)] attribute on controllers or actions.

Example:

[ApiExplorerSettings(IgnoreApi = true)]
public class DeprecatedController : ControllerBase
{
    public IActionResult Get()
    {
        // action implementation
    }
}

10. How can I enable Try-It-Out feature in Swagger UI?

The Try-It-Out feature is enabled by default in Swagger UI. When you run your application, Swagger UI will display a "Try it out" button next to each API endpoint. Clicking this button will allow you to interactively test the API calls. Ensure that your endpoints are correctly configured to allow CORS, so the Swagger UI can make requests to your API.

services.AddCors(options =>
{
    options.AddPolicy("AllowAllOrigins",
        builder =>
        {
            builder.AllowAnyOrigin()
                   .AllowAnyHeader()
                   .AllowAnyMethod();
        });
});

app.UseCors("AllowAllOrigins");

This configuration adds CORS support to your application, allowing requests from any origin, header, and method.