未显示 Swagger 响应描述

Question

我目前正尝试在 Swagger UI 中显示特定响应的描述，但似乎没有真正涵盖所有方面的文档，以及我提供的所有示例从 Get started with Swashbuckle and ASP.NET Core 开始尝试在 .NET Core 3.1 中不起作用...

        /// <summary>
        /// Test route...
        /// </summary>
        /// <returns></returns>
        /// <response code="200">This is a test</response>
        [HttpGet]
        [ProducesResponseType(typeof(string), StatusCodes.Status200OK)]
        public IActionResult Get()
        {
            return Ok("Hello World");
        }

我的 .csproj 也包含以下内容：

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

Swagger UI 最终看起来像这样（如您所见，"Descriptipn" 列不包含可能应该包含的 "This is a test" 文本）。我错过了什么吗？

我也添加了[SwaggerResponse(StatusCodes.Status200OK, ...)]，但没有任何变化。

Answer 1

在您的项目属性中，您应该检查 blade Build 下的 Output XML documentation file。然后在你的 startup 文件中：

services.AddSwaggerGen(c =>
{
    //rest of your code

    //i'm using the default path generated, but you can adjust it as you want
    var XMLPath = AppDomain.CurrentDomain.BaseDirectory + nameof(MyNamespace) + ".xml";
    if (File.Exists(XMLPath))
    {
        c.IncludeXmlComments(XMLPath);
    }
});

如果仍然无效，请检查 xml 文件是否出现在 bin 文件夹中。如果不检查 Visual Studio 内的属性并将 Copy to output directory 调整为 Copy 或 Copy if newer.

Answer 2

事实证明，[SwaggerResponse] 工作正常，但在此之前，我需要在我的 Startup 中 "enable annotations"...

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

        config.EnableAnnotations();
    });

Answer 3

根据 official docs，这是通过 XML 评论完成的：

<response code="201">This is a test</response>

评论需要链接Swagger

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

未显示 Swagger 响应描述

Swagger response description not shown

c#

.net-core

swagger

swagger-ui