Swagger API 未刷新文档

Question

我正在使用 Swagger API 来记录我的 REST 服务。 早些时候，我的控制器方法没有信息丰富的注释，因此 Swagger API 没有显示说明，但现在即使在更新注释后，我也没有在突出显示的区域中获取方法说明。

    /// <summary>
    /// Gets the consumer scores by retailer id and return id
    /// </summary>
    /// <param name="retailerId"></param>
    /// <param name="returnId"></param>
    /// <returns></returns>

我错过了什么吗？

Answer 1

为了让 Swashbuckle 读取您的 XML 注释，您需要为目标项目启用 XML 文档文件。 除此之外，您还需要将 Swashbuckle 指向启动配置中的该文件。

来自 Swashbuckle 文档：

打开项目的“属性”对话框，单击“构建”选项卡，然后 确保选中“XML 文档文件”。这将产生一个 包含构建时所有 XML 注释的文件。

此时，任何未使用 XML 注释的类或方法 评论将触发构建警告。要抑制这种情况，请输入 将警告代码“1591”添加到“抑制警告”字段中 属性对话框。*

配置 Swashbuckle 将文件上的 XML 注释合并到 生成的 Swagger JSON：

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1",
        new Info
        {
            Title = "My API - V1",
            Version = "v1"
        }
     );

     var filePath = Path.Combine(PlatformServices.Default.Application.ApplicationBasePath, "MyApi.xml");
     c.IncludeXmlComments(filePath);
}

使用摘要、评论和响应标签来注释您的操作

/// <summary>
/// Retrieves a specific product by unique id
/// </summary>
/// <remarks>Awesomeness!</remarks>
/// <response code="200">Product created</response>
/// <response code="400">Product has missing/invalid values</response>
/// <response code="500">Oops! Can't create your product right now</response>
[HttpGet("{id}")]
[ProducesResponseType(typeof(Product), 200)]
[ProducesResponseType(typeof(IDictionary<string, string>), 400)]
[ProducesResponseType(typeof(void), 500)]
public Product GetById(int id)

重建您的项目以更新 XML 注释文件并导航到 Swagger JSON 端点。请注意描述如何映射到 对应的 Swagger 字段。

Answer 2

就我而言，我没有在 VS Mac 中启用为发布模式生成 XML 文档的选项：
只需转到项目属性并在“编译器”选项卡下，选中“生成 XML 文档”复选框即可。