swagger-api / swagger-api/swagger-ui
Render query param examples as placeholders
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 29k
- Forks
- 9.3k
- Avg merge
- 2d 23h
- Merged PRs (30d)
- 25
Description
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.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by tracing Swagger UI's query-parameter input rendering and how it distinguishes example from default; the issue does not name a source file or test. Done means optional query parameters use their example values as input placeholders rather than submitted defaults, while default values still prefill the input.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, openapi
- Domain
- frontend
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100