Analysis

Personas

When it comes to usability one of the main key points that should be taken into consideration is knowing the different personas of your product.

I can identify at least 5 different groups that will use swagger-ui within a products lifecycle:

API developer
Client developer
Consultant introducing the API to client developer
Tester
Other Stakeholders (e.g. Product Owner, non technical users in case there is no frontend, ...)

API developer

The developer of the api may have the following interessts in using swagger-ui:

Testing within product development lifecycle

The developer may use swagger-ui to test the api's functionality.
He exactly knows what part of the api he will be interacting with and so the part of swagger-ui.
Interact with the api

In addition the developer may use swagger-ui to accomplish some task that requires interacting with the api. It is possible that the task requires multiple subsequent request to be run.
Gathering informations

If the developer is new to the project he may want to read the documentation of the service. In addtion he wants to try out some methods to understand the api.

Client developer

The client developer has the following inerests in using swagger-ui:

Acquiring interface informations

The developer may have the task to evaluate the interface provided by an api. He will use swagger-ui's documentation in order to know what data he needs to provide and what data he will receive. In addition he may use the try out.
Manual testing

The developer may test any part of the api using swagger-ui.

Consultant introducing the API to client developer

A consultant may use swagger-ui to preset some functionality or demonstrate a use case.

Showing basic documentation structure

When onboarding a new client developer a consultant may use the documentation to outline the different parts of the api.
Demonstrate API

He may use swagger-ui to demonstrate different scenarios.

Tester

When testing the API a tester may use swagger-ui to interact with the api.

Testing valid data

A tester may be given some test data he needs to process through swagger-ui.
Testing invalid data

A tester may need to test the api with invalid inputs.

Other Stakeholders

Non technical stakeholders may use swagger-ui for the following use cases:

Requirements check

A requirements manager may use swagger-ui for testing given requirements.
Health check

A PO might use swagger-ui to check for the api's health.

Scenario Analysis

Testing single operation

A single operation may be easy to find, but this depends on the tag and operation count per tag.
If there are many operations per tag it is hard to find the operation that you are looking for.

Steps: scroll to operation > expand operation > click Try out
Step Count: 3
Testing n subsequent operations

In case of testing n subsequent operations a developer needs to scroll a lot. Most of the time it is more efficient to close the operation then to scroll all the way down to the next operations.

Steps: [scroll to operation > expand operation > click Try out > collapse operation] * (n - 1) + [scroll to operation > expand operation > click Try out]
Step Count: 4n - 1
Documentation and Testing operation

In case of testing an operation it may be required to jump to some documentation part like Schemas section or other operation for gathering further information. This results in lot of scrolling.
Testing invalid data In case of analyzing the API it would be useful to test invalid data (data that does not match OAS Schema constrains).

Usability Issues

Try-Out Section nested within documentation So basically there are to main use cases documentation and try out that should be independent from my perspective. Currently the try out is nested within the documentation. This creates an overhead of steps need to get to the try out.
Scroll overhead Testing either multiple subsequent operations or jumping between try-out and documentation is extremely painful because of the scrolling overhead.
Testing invalid data Testing invalid data is currently not possible because it will be validated in swagger-ui.

Possible Solution

Swagger-UI should split their main features documentation and try out.
Make the ui more flexible to remove the scrolling overhead needed when switching between multiple operations or documentation.

This could be achieved by introducing a tab based ui. It could be structured like VS Code. There could be two tab types. One tab open all the time is the documentation as we all know. But it has no try out. The other type of type is a operation try out tab. With this customers have the ability to organize their view.

The basic structure should consist of a navigation bar and a tab area which can be splitted. The tab area always contains the documentation tab.

The navigation bar is showing: information, operations, schemas sections for quick access and highlights the current documentation expanded section in view port. A customer should be able to reveal the operation in the documentation tab by clicking on the operation in the navigation bar. The customer should in addition be able to open the operation as try out tab.

In respect to the screen size the try out tab will be opened either by side or as new tab in the unsplitted tab area. In addition for mobile the navigation bar could be full size and expandable from the top(todo create mobile prototype).

Testing single operation

Using the navigation bar or the documentation one can open an operation very easily If there are many operations per tag it is hard to find the operation that you are looking for.

Steps: click popout button
Step Count: 1
Step Improvement count: 2
Testing n subsequent operations

One can open a operation in a new tab by one click using the pop out button.

Steps: n
Step Count: n
Step Improvement count: 3n - 1
Documentation and Testing operation

In case of testing an operation it may be required to jump to some documentation part like Schemas section or other operation for gathering further information. The flexible tab system allows the user to open any tab or documentation side by side.