如何在 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)

在这里，对于名为“value”的参数，我想提供一个示例 EAN 条形码，例如“QN1318481”来记录示例值（不是示例代码片段）

Answer 1

如果您需要使用 Swagger 生成 OpenAPI 文档，那么使用标签example内的值是完全可以的。param根据包含 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 会自动使用这个值，前几天刚尝试过，效果很好