Swagger-ui: Render query param examples as placeholders

[lucasmfredmark]

I have a lot of optional query params which have examples defined on them. In most cases only a few of the query params are specified in the request.

Currently when defining an example on a query parameter, the example value is being set in the input field by default. This means that the examples become _request defaults_, which in most cases is undesirable. Setting the example values as placeholders on the input would make more sense, since they are not _defaults_ anymore and can be specified manually. Considering that query params by default are optional, I think that in most cases this is what the user wants.

The default param on a query parameter currently also prefills the input with a value, but contrary to the example param I think that this is the preferred way to define a request default. If I want to define an example without it becoming the default, I currently have to add an example to the description of the parameter.

It also seems to me that current implementation contradicts the intended behavior:

Do not confuse example values with default values. An example illustrates what the value is supposed to be. A default value is what the server uses if the client does not provide the value.

I can't think of any potential side effects that this could have.

[webron]

It's funny you quote the spec, because it actually means that it makes no sense to use the default value as a default value in the UI because the client/server will assume it if it's not provided. Examples are intended as documentation and that's why they are being used. If you can share an example definition to explain your use case further, that would be beneficial.

[lucasmfredmark]

I guess in my situation it would just be more beneficial if the example was a _hint_ rather than a default. See example below.

The examples defined on these query params are there to tell the user in what format the input value should be. All of the query parameters are optional, but when providing an example the input already has a value. This is counterintuitive because most often the user would specify only the query params they want to provide, and now they have to remove the values in the inputs that are not needed.

Query parameters are optional by nature, which is why I think it should be up to the user to decide which query parameters to include. Treating examples are defaults forces the user to include query parameters by default, which I think is undesirable in most cases.

A solution could be to display examples beside the input, and allowing them to easily apply an example value to the input by clicking on it. This way the user can choose to use the example value or not.

I hope this makes sense 😄

[goncalorodrigues]

I completely agree with @lucasmfredmark . I have the same problem / request. In fact, if you have a default value and an example and if you click the “Try it out” button and then click the “Execute” button, the request will be executed with the example as parameter values and not with the default ones.

[killergege]

Same issue for me : we use the example field to explain the expected format or examples of values, but it makes no sense to have them prefilled when the user clicks on "try"
As the OP, we have to put the example in the description to workaround that issue (which is even annoying for us as we are using Swashbuckle + C# XML autogenerated doc so it means to not properly use the doc headers in the code).

So, as suggested above, I think it would be better that examples are used as hints, but are not use to prefill the fields.