swagger-api / swagger-api/swagger-ui
Swagger UI 2.9.2 usability issues
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 29k
- Forks
- 9.3k
- Avg merge
- 2d 23h
- Merged PRs (30d)
- 25
Description
I just upgraded from Swagger 2.7.0 to 2.9.2
There are a number of UI issues in the new design. I apologize for being overly critical, but together they are significant enough that we're probably going to revert to 2.7.0
In general, the new design is more overwhelming (extra text), wastes space, and requires more work in terms of clicking and scrolling.
Extra click
First, the user cannot just enter values and click "Try it out" (Execute) as they could in 2.7.0
Now they need to click "Try it out" to activate the form, then enter values, then Execute.
parameters
Each param takes too much height and has redundant text.
On the right, when the form is active, the same text is displayed 3 times.
foo
[foo - foo]
IMO, the Java function parameter is an implementation detail and should not be displayed. If the default description is equal to the variable name, it also should not be displayed.
I don't think the primitive type needs to be displayed for most APIs , maybe this could be a display option integer($int32)
(path) is not that useful and adds to the height waste. I think just have a heading for each parameter type instead and group the parameters of the category underneath.
I think the path variable params should be sorted as they are in the path, not alphabetical.
Curl and Request URL
Curl and Request URL are under Responses, but they should be associated with the request.
The curl box is too tall and wastes space.
IMO, the Curl command should be within a tab, or be a button that copies the command.
I think a better design would be to have a request URL preview above the Execute button that updates as you change values. Next to this would be a copy URL button and a copy Curl command button.
Clear button
It's a bit ambiguous whether this clears the form or clears the response. For clarity, I think it should be next to "Response body". A "Clear Values" button could be added top-right where Cancel is now.
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 comparing the Swagger UI 2.9.2 and 2.7.0 interaction flow described in the issue, focusing on parameter forms, Curl and Request URL placement, and the Clear button. The requested work needs an agreed subset of these usability changes; done should be defined by the resulting UI behavior and any corresponding tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100