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>

我有什么遗漏吗？

- tRuEsAtM

---

当你提到“使用swagger API”时，你指的是什么？你具体使用哪个库从C＃生成swagger文档？ - mclark1129

我正在使用 Swashbuckle.AspNetCore 与我的 C# Web API。 - tRuEsAtM

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字段。

- mclark1129

---

这对我来说是最好的解决方案。 - 8protons