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

user_6305105 0
Viewed 1603

If you are using C# XML doc comments and you have a param to provide a description of a function parameter, how can you provide an example value (e.g. "San Francisco" or 5)?

Here is an example:

/// <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)

Here, for the parameter named "value", I would like to provide an example EAN barcode, e.g. "QN1318481" to document an example value (not an example code snippet)

swagger comments xml c#
1 Answers

If you need this to generate a OpenAPI documentation using Swagger, it's perfectly fine to use example value inside param tag. According to Include Descriptions from XML Comments (point 3) you can write something like

/// <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 will automatically use this value, just tried the same few days ago and it works fine

user_47286850
Related