swagger-api / swagger-api/swagger-ui

Swagger UI 2.9.2 usability issues

Open
#4,972 3 comments 16 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type: support
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.