如何在 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 文档，则可以在 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 会自动使用这个值，几天前刚试过，效果很好

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

How to specify example value for a parameter in C# XML doc comments?

c#

xml

swagger

comments