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

Hi, probably swagger doesn't support summary description for minimal-api. I would recommend to create issue on github github.com/domaindrivendev/Swashbuckle.AspNetCore/issues — DarkSideMoon
– DarkSideMoon, Commented Oct 31, 2021 at 20:58
Even if swagger+minimal apis supported xml docs app.MapGet is a local call which is not a valid target for XML comment. Check out the generated xml - it should be empty. — Guru Stron
– Guru Stron, Commented Oct 31, 2021 at 21:09
Also based on this github item it seems there will not be much ways to customize the generated swagger doc ATM. — Guru Stron
– Guru Stron, Commented Oct 31, 2021 at 21:29
@davidfowl thanks for confirming that this doesn't work, I tried everything to no avail. Without the ability to describe what the APIs do via Swagger, minimal APIs lose much of their appeal :-( — Eric Mutta
– Eric Mutta, Commented Nov 5, 2021 at 2:38

Chuen Lee · Accepted Answer · 2022-05-20 11:09:35Z

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:

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>

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));
});

Collectives™ on Stack Overflow

Swagger ASP.NET Core Minimal API include XML comments files

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related