如何在C#XML文档注释中指定参数的示例值

Question

如果您使用C#XML文档注释，并且您有一个param来提供函数参数的描述，那么如何提供示例值(例如"San Francisco"或5(？

这里有一个例子：

/// <summary>
/// Lookup EAN barcode value, return product data
/// </summary>
/// <remarks>Lookup an input EAN barcode and return key details about the product</remarks>
/// <param name="value">Barcode value</param>
/// <returns>JSON describing matching product data to the entered barcode</returns>
[HttpPost, Route("ean")]
public BarcodeLookupResponse EanLookup([FromBody]string value)

这里，对于名为"；值"；，我想提供一个EAN条形码的例子；QN1318481"；记录示例值(而不是示例代码片段(

Answer 1

如果您需要使用Swagger生成OpenAPI文档，那么在param标记中使用example值是非常好的。根据包含XML注释中的描述(第3点(，您可以编写类似的内容

/// <summary>
/// Lookup EAN barcode value, return product data
/// </summary>
/// <remarks>Lookup an input EAN barcode and return key details about the product</remarks>
/// <param name="value" example="QN1318481">Barcode value</param>
/// <returns>JSON describing matching product data to the entered barcode</returns>
[HttpPost, Route("ean")]
public BarcodeLookupResponse EanLookup([FromBody]string value)

Swagger UI将自动使用这个值，几天前刚刚尝试过，它运行良好