Swagger API没有刷新文档

时间:2017-03-15 17:21:24

标签: c# asp.net-web-api swagger swashbuckle

我正在使用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>

enter image description here

我错过了什么吗?

1 个答案:

答案 0 :(得分:9)

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

来自Swashbuckle Documentation

  

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

     

此时,任何未使用XML注释的类或方法   注释将触发构建警告。要压制这个,请输入   警告代码“1591”进入“Supress warnings”字段   属性对话框。*

     

配置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 Comments文件并导航到   Swagger JSON端点。请注意描述如何映射到   相应的Swagger字段。