Swagger ASP.NET Core Minimal API 包含 XML 注释文件答案

【问题标题】：Swagger ASP.NET Core Minimal API include XML comments filesSwagger ASP.NET Core Minimal API 包含 XML 注释文件
【发布时间】：2022-05-20 19:09:35
【问题描述】：

我需要 Swagger 生成 XML API 文件文档，包括 UI 以测试操作。

在我的项目中使用 ASP.NET 时，生成了 deps XML 文件，一切正常。

我已经设置： -项目文件文档 - 编写并获取路径

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

当我运行我的项目时，cmets 没有出现。

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

创建新标签：minimal-api

【问题讨论】：

嗨，swagger 可能不支持最小 api 的摘要描述。我建议在 github github.com/domaindrivendev/Swashbuckle.AspNetCore/issues 上创建问题
即使支持 swagger+minimal apis xml 文档 app.MapGet 是一个本地调用，它不是 XML 注释的有效目标。查看生成的 xml - 它应该是空的。
同样基于this github项目，自定义生成的swagger doc ATM似乎没有太多方法。
目前不支持。
@davidfowl 感谢您确认这不起作用，我尝试了 everything 无济于事。如果无法通过 Swagger 描述 API 的功能，最小化 API 就会失去很多吸引力：-(

标签： api asp.net-core .net-6.0

【解决方案1】：

有同样的问题。

我使用的是 .NET 6.0.202，Swashbuckle.AspNetCore 版本 6.3.1

从这里发现：https://github.com/domaindrivendev/Swashbuckle.AspNetCore/issues/2267

可以使用以下结构来完成：

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

}

然后在Program.cs

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

// map endpoints
app.MapWeatherRoutes();

另外，请确保：

csjproj 文件包含<GenerateDocumentationFile>，如下所示

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

在Program.cs 中配置 Swashbuckle 时，请确保将选项配置为使用 XML 文件。也描述在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));
});

【讨论】：