Swagger UI 2.9.2 usability issues

[arlowhite]

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.

[shockey]

Hi @arlowhite!

I just upgraded from Swagger 2.7.0 to 2.9.2

Neither of these versions are Swagger UI versions - we jumped straight from 2.2.10 to 3.0.0. Since you mention a new design, I'm going to assume you were on 2.x and are now seeing 3.x.

See our version detection documentation for more guidance on how to figure out what version you're using!

In general, the new design is more overwhelming (extra text), wastes space, and requires more work in terms of clicking and scrolling.

Fair point - a "compact mode" was requested in #4458, but we haven't seen any community involvement around reading a stylesheet for it.

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.

This is a fair point, and was raised last year over at #2805. We're open to proposals around changing this behavior, but it's important that any change is an improvement both for people reading the documentation and interacting with the endpoints.

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.

This is a known issue over at #3920.

IMO, the Java function parameter is an implementation detail and should not be displayed.

Not sure what you mean by Java function parameter - can you elaborate?

I don't think the primitive type needs to be displayed for most APIs

I disagree - this is quite useful if you're unfamiliar with the API and are filling in a value. If you want to disable it, you can write a plugin that modifies this behavior.

(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.

Interesting - AFAIK, we haven't had that request before. I think you can do this with a custom plugin, if you're interested.

I think the path variable params should be sorted as they are in the path, not alphabetical.

I disagree - while this method of sorting makes sense if you only have path parameters, but if other types are present as well, it makes everything seem jumbled unless you know what's happening behind the scenes.

Of course, you could write your own plugin 😄

---

Generally:

We recently did a (non-public) review of our UX/UI with a team of user experience designers, which included the designers reviewing all of the open UX/design/presentation tickets we have.

I'm not sure where exactly we are on that, but perhaps @webron would be open to sharing a draft with you to see if the changes would address your pain points.

[lrozenblyum]

UX of swagger-ui is truly not ideal in the modern versions (it was much better years ago). Are there any plans for improvements?

[mjsmith707]

Also hoping there will be some improvement to this. I've been using 2.x for several years now but recently moved to 4.x and the usability is really just so much worse for all the reasons described above.

I'd say my biggest complaint by far is the amount of scrolling required even on a 1440p monitor. There is simply way too much whitespace.