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

Question

如果您使用 C# XML doc cmets，并且您有一个 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”记录一个示例值（不是示例代码sn-p）

Answer 1

如果您需要它来使用 Swagger 生成 OpenAPI 文档，那么在 param 标记内使用 example 值是完全可以的。根据Include Descriptions from XML Comments（第 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 会自动使用这个值，前几天刚试过，效果很好