Swagger ASP.NET Core Minimal API include XML comments files

Question

I need Swagger generate XML API file documentation, include UI to test operations.

When use ASP.NET in my project, deps XML files are generated, everything is OK.

I've set: -Project File documentation -Wrote and get the path

var filePath = Path.Combine(System.AppContext.BaseDirectory, "Minimal_API.xml");
x.IncludeXmlComments(filePath);

And when I run my project, the comments don't show up.

/// <summary>
/// Gets the list of all records
/// </summary>
app.MapGet("/weatherforecast2", () =>
{
    var summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };
    var forecast = Enumerable.Range(1, 5).Select(index =>
       new WeatherForecast
       (
           DateTime.Now.AddDays(index),
           Random.Shared.Next(-20, 55),
           summaries[Random.Shared.Next(summaries.Length)]
       ))
        .ToArray();
    return forecast;
})

Create new tag: minimal-api

Answer 1

Had the same issue.

I'm using .NET 6.0.202, Swashbuckle.AspNetCore version 6.3.1

Found out from here: https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/2267

It can be done by using the following structure:

public static class WeatherEndpoints
{
    public static void MapWeatherRoutes(this IEndpointRouteBuilder app)
    {
        app.MapGet("/weatherforecast2", GetWeather);
    }

    /// <summary>
    /// Gets the list of all records
    /// </summary>
    /// <returns></returns>
    private static IResult GetWeather()
    {
        var summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };
        var forecast = Enumerable.Range(1, 5).Select(index =>
                new WeatherForecast
                (
                    DateTime.Now.AddDays(index),
                    Random.Shared.Next(-20, 55),
                    summaries[Random.Shared.Next(summaries.Length)]
                ))
            .ToArray();
        return forecast;
    }

}

Then in Program.cs

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// map endpoints
app.MapWeatherRoutes();

Also, make sure:

1. The csjproj file contains <GenerateDocumentationFile> as below

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <GenerateDocumentationFile>true</GenerateDocumentationFile> <---- this needs to be added 
    <NoWarn>$(NoWarn);1591</NoWarn>
  </PropertyGroup>

2. When configuring Swashbuckle in Program.cs Ensure the options are configured to use the XML file. Also described in https://github.com/domaindrivendev/Swashbuckle.AspNetCore#include-descriptions-from-xml-comments

builder.Services.AddSwaggerGen(opts =>
{
   
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    opts.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});