Example values(placeholder) for query parameters in Swagger (swashbuckle)

Question

I'm using swashbuckle in net core to create a swagger documented API.

The function I have uses query parameters. I wanted to add a short description for each query parameter, next to the textbox where the parameter value is entered. I achieved this by using XML comments:

/// <param name="propertyId">The integration property ID. Events related to presentations related to this ID will be returned</param> public ActionResult GetEvents([BindRequired] string propertyId){}

This works fine, but it also adds the description text in the textbox placeholder:

I saw that the placeholder can be changed, if the generated JSON has an 'example' value for the query parameter. How do I add the example value, or change the placeholder in general using the XML comments or something similar?

Yes, or at least to remove the description text from the textbox field and make it empty :) Right now it looks like it is composed of the Name + Description — Filip5991
– Filip5991, Commented Dec 15, 2021 at 15:19

Yiyi You · Accepted Answer · 2021-12-16 07:34:58Z

9

You can try to add example="xxx" into <param></param> to add the example value and change the placeholder.

 /// <param name="propertyId" example="id">The integration property ID. Events related to presentations related to this ID will be returned</param> public IActionResult GetEvents([BindRequired] string propertyId) { ... }

result:

answered Dec 16, 2021 at 7:34

Yiyi You

18.4k1 gold badge19 silver badges31 bronze badges

Sign up to request clarification or add additional context in comments.

6 Comments

Filip5991 Over a year ago

One more question, what if the parameter is of type DateTime? Setting a string in the example that way does not work, only possibilities that did work were example = " " (sets placeholder to starting date) and example = "2021-12-12" (sets it do datetime in the yyyy-MM-ddTHH:mm:ss format). Is there a way to use string as the placeholder here?

Filip5991 Over a year ago

I realized that this does provide an example value, but it does not change the placeholder. prnt.sc/23a7e8y If I were to click try it out, the text value would be there, and I need it to be empty, with a custom placeholder

Sam Jones Over a year ago

@Yoro, i thought you could only use the AddSwaggerExamplesFromAssemblies for request/response objects and not querystring requests?

kubo Over a year ago

Does anyone know how to use an example for a List<> query parameter?

interesting-name-here Over a year ago

@kubo i know this is late but looking at the code: github.com/domaindrivendev/Swashbuckle.AspNetCore/blob/… if you just put it in as a json array string in the example="["test","test2"]" may work

|

Collectives™ on Stack Overflow

Example values(placeholder) for query parameters in Swagger (swashbuckle)

1 Answer 1

6 Comments

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

6 Comments

Related