swagger-api / swagger-api/swagger-ui

Usability improvement

Open
#2,805 11 comments 40 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

cat: user experience needs: UX/design input P2 type: feature version: 3.x
Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Being used to the 2.x UI (ie: ibm.biz/restapi), to me it wasn't obvious that the "Try it out" button now enters into a development mode. I was expecting the "Try it out" button to actually execute a request, like it did in 2.x.

With 3.x, if I want to try out multiple endpoints I must click "Try it out" for each one, and then execute.

This issue is to suggest that we have a global toggle at the top of the UI that enters the "development mode", so that you can keep the default "documentation mode", but have an easier way to enter the development mode for all the endpoints. This would reduce the amount of buttons in your UI by 1 for every endpoint.

If we think about it, the "Authorize" button at the top means nothing if we're in documentation mode, since we won't be invoking any APIs.

So I suggest we replace the Authorize button with something like "Configure UI" (or similar) where the popup window/wizard would have a checkbox that said "Enable development mode", and when that checkbox was enabled then the authorization configuration inputs would show up and every endpoint would have the Try it out button, ie: execution.

This also creates a place where other configuration can go in the future from extenders of the UI - for example, if someone wants to hook up generators from the UI, filter tags, etc.

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 tracing the UI entry points for the "Try it out" and "Authorize" controls and how they switch between documentation and development mode. Define the global configuration flow and confirm that enabling development mode applies to every endpoint while preserving a documentation-only default; done means the proposed configuration and authorization behavior is consistent across the UI.

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
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.