Swagger ASP.NET Core Minimal API 包括 XML 注释文件

Question

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

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

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

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

当我运行我的项目时，评论不会显示。

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

Answer 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();

另外，请确保：

1. 该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>

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