CODEWITHSUNDEEP
c#xmlswaggercomments
A X
A X

Reputation: 1056

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

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)

Upvotes: 5

Views: 5093

Answers (1)

Pavel Anikhouski
Pavel Anikhouski

Reputation: 23258

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

Upvotes: 3

Related Questions