我正在使用Swagger API来记录我的REST服务.
之前我的控制器方法没有提供信息性的评论,因此Swagger API没有显示描述,但现在甚至在更新评论后,我没有在突出显示的区域中获得方法描述.
之前我的控制器方法没有提供信息性的评论,因此Swagger API没有显示描述,但现在甚至在更新评论后,我没有在突出显示的区域中获得方法描述.
/// <summary>
/// Gets the consumer scores by retailer id and return id
/// </summary>
/// <param name="retailerId"></param>
/// <param name="returnId"></param>
/// <returns></returns>
我错过了什么吗？
解决方法
为了让Swashbuckle从您的XML注释中读取,您需要为目标项目启用XML文档文件.除此之外,您还需要在启动配置中将Swashbuckle指向该文件.
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.
