c# - Swagger API 不刷新文档

Question

我正在使用 Swagger API 来记录我的 REST 服务。早些时候我的 Controller 方法没有信息性注释，所以 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 Documentation :

Open the Properties dialog for your project, click the "Build" tab and ensure that "XML documentation file" is checked. This will produce a file containing all XML comments at build-time.

At this point, any classes or methods that are NOT annotated with XML comments will trigger a build warning. To supress this, enter the warning code "1591" into the "Supress warnings" field in the properties dialog.*

Configure Swashbuckle to incorporate the XML comments on file into the generated 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);
}

Annotate your actions with summary, remarks and response tags

/// <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)

Rebuild your project to update the XML Comments file and navigate to the Swagger JSON endpoint. Note how the descriptions are mapped onto corresponding Swagger fields.