swagger-ui
swagger-ui copied to clipboard
swagger-api
Render query param examples as placeholders
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.
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.
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 😄
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.
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.
I'd like to bump this issue with another behavior that is incredibly annoying and related to prefilling the query param inputs. When you have a pattern validating the query parameter but the value is optional, prefilling the field means that I have to manually erase the value, at which point the validation kicks in and prevents me from sending perfectly valid request.
The only remedy if I want Swagger UI to work is to remove the examples, then the field is actually empty on "Try it out" (but still, any keypress in the input triggers the validation anyways and prevent submission).
It very well might be a separate bug/feature, but OP's suggestion would remedy my issue and would also be be just generally good UX and in line with the intended use case of query parameters, which are optional.
+1 for me.
My use case is less important than the OP and others. I just wanted to customize Swagger UI's placeholder values for query parameters, because my descriptions are long, and in the absence of an example, the placeholder is a copy of the parameter description -- this then gets truncated and the resulting UX is undesirable.
I thought it might be nice to have a placeholder that provides examples of real world values, as OP, and that's when I found this bug report, because I can't do that without the examples becoming pre-filled as defaults.
This issue looks too simple to implement. Why is it still open? I can send PR if it is the only thing that missing in order to get the correct behavior.
@char0n, @shockey I don't know who is responsible to take further decisions. Can you suggest what should be next actions to get this feature released?
Is it possible to get any movement or interest in this Issue? I think the current behavior of prefilling the example value over the default value is not correct.
Perhaps the options should include a default value as well as IsOptional. And the Generated UI could use the default value instead of the example. The example can thus serve a documentation only.
+1 from me - also had to use the description to display an example value.
fileIdParam:
name: fileId
in: path
required: true
description: "Uniquely identifies a file.<br/><br/>Example: 48e3cece-37c6-4d92-b0d8-3620ef27d219"
schema:
type: string
format: uuid
Myself find this being actually problematic as well. An example value should just be an example, and default being an actual value.
I've partially solved it with a plugin:
const DontSetParametersDefaultsPlugin = () => ({
wrapComponents: {
JsonSchemaForm: (Original, { React }) => ({ value, description, ...props }) => {
return React.createElement(Original, { ...props, description: value, dispatchInitialValue: true })
}
},
});
But this version doesn't show placeholders.
If I remove the dispatchInitialValue: true it does show placeholders, but the internal state is not updated and the "Execute" button still sends a request with example values.
