Как указать примерное значение параметра в комментариях C# XML do c?

Question

Если вы используете C# XML do c комментарии и у вас есть 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

Если вам это нужно для создания документации OpenAPI с помощью Swagger, вполне нормально использовать значение 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 автоматически будет использовать это значение, просто попробовал те же несколько дней go и работает нормально