使用 [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 属性和 XML 评论中放置了描述。似乎没有任何效果。

我是不是漏掉了一些简单的东西？

P.S。在不使用 FromQuery 的其他情况下，它似乎确实有效。

P.P.S。已解决...问题是 SomeDataRequest class 在另一个项目中，因此它的 XML 文档文件没有被 Swashbuckle 处理。

Answer 1

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

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

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

第一步是打开每个程序集的生成文档选项。在我的项目中，使用文档生成 xml 文件的配置如下：

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

在每个程序集中启用此功能后，文档文件将输出到我的主要程序集 dll 文件所在的同一文件夹，即 \Project.API\bin\Debug\netcoreapp2.2。

如果这对您不起作用，您可以尝试使用 DocumentationFile compiler option.

显式设置输出路径

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

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

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

如果这对您不起作用，您需要找到 xml 文件所在的位置，然后使用 IncludeXmlComments().

将它们一一添加

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

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

使用 [FromQuery] 时如何记录 Swagger/Swashbuckle 参数说明

How to document Swagger/Swashbuckle parameter descriptions when using [FromQuery]

c#

swagger

.net-core

swashbuckle