使用 [FromQuery] 时如何记录 Swagger/Swashbuckle 参数描述

Question

我的 api 端点：

[HttpGet]
public ActionResult GetSomeData([FromQuery] SomeDataRequest request) {
    return File(returnImage(), "image/png");
}

public class SomeDataRequest {
  /// <summary>
  /// Description 1
  /// </summary>
  [Description("description 1")]
  public string foo;

  /// <summary>
  /// Description 2
  /// </summary>
  [Description("description 2")]
  public string bar;
}

当我打开 Swagger UI 时，它没有显示SomeDataRequest.

我已经Description按照This answer 的建议在属性和 XML 注释中放置了描述。似乎没有任何效果。

我错过了一些简单的东西吗？

PS 它似乎在FromQuery不使用时在其他场景中工作。

PPS 已解决... 问题是SomeDataRequest该类在另一个项目中，因此 Swashbuckle 未处理其 XML 文档文件。

Answer 1

虽然这个问题似乎很老了，并且OP设法解决了他的问题，但没有人写出这个问题的完整答案。因此，为了帮助像我这样可能试图解决同样问题的人，我将写出对我有用的内容（这似乎与OP的解决方案相同）。

当您有多个程序集并且您仅为主程序集而不是 DTO 类可能位于的其他程序集生成文档文件时，似乎会发生此问题。

因此，要修复它，您需要做两件事：在每个程序集（或者至少是您的 DTO 所在的程序集）上打开文档生成，并告诉 swashbuckle 这些 xml 文件在哪里。

第一步是打开每个装配上生成文档的选项。在我的项目中，成功生成带有文档的 xml 文件的配置如下：

 <PropertyGroup>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
 </PropertyGroup>

在每个程序集中将其转换后，文档文件将输出到我的主程序集 dll 文件所在的同一文件夹，即\Project.API\bin\Debug\netcoreapp2.2.

如果这对您不起作用，您可以尝试使用DocumentationFile编译器选项显式设置输出路径。

之后，您需要告诉 Swashbuckle 这些 xml 文件在哪里。如果它们都在主程序集 dll 文件夹中，您可以使用以下代码片段来收集它们。

List<string> xmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml", SearchOption.TopDirectoryOnly).ToList();
xmlFiles.ForEach(xmlFile => swaggerGenOptions.IncludeXmlComments(xmlFile));

免责声明：此片段不是我制作的。我从github 上关于同一主题的问题中获取了它。它只是通过探测主程序集构建文件夹来查找 xml 文件。

如果这对您不起作用，您将需要找到 xml 文件所在的位置并使用 .xml 文件将它们一一添加IncludeXmlComments()。

之后，您应该获得要在 Swagger 页面上显示的参数的文档。

仅供参考，我使用Swashbuckle 3.0.0在.NET Core 2.2应用程序上执行此操作，但我相信这仍然适用于该库的较新版本，因为 github 上关于此问题的线程有最新的答案。