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 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.

Swagger API 不刷新文档

Swagger API not refreshing the documentation

c#

asp.net-web-api

swagger

swashbuckle