swagger-api / swagger-api/swagger-ui

Provide an easy way to enter custom URL to try-it feature

Open
#4,735 3 comments 12 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

cat: try-it-out cat: user experience needs: UX/design input specification: 3.x type: enhancement
Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Content & configuration

Swagger/OpenAPI definition (using the .json format):

https://apicatalog.oraclecloud.com/public/v1/orgs/oracle-public/apicollections/database/csdbr-13/apis/accessrules/canonical

Swagger-UI configuration options:

We use default setup I believe - see https://apicatalog.oraclecloud.com/ui/views/swaggerui3/oracle-public/java/18.1.4

Is your feature request related to a problem?

I am trying to find a way to provide a default list of alternate URLs the user can use to test his service with the ability to overwrite the default value, using an efficient UX layout.

I have try using the current 'servers' option, but there is no easy way to let the user enter his own URL as a replacement to the default values provided, or when there is none.

Describe the solution you'd like

When there is no default value, the user should see an input field to enter some URL before to have the "try-it" feature enabled.
Once he has enter some value, or there are multiple values provided, he should be able to use a drop-down list to select an existing value or have the option to enter a new value.

Describe alternatives you've considered

Try to use the 'servers' property in OAS 3.0, but could not find an effective way to do this without to waist a lot of screen real estate.

Swagger snippet:

  "servers": [
    {
      "url": "https://apicatalog.us.oracle.com/"
    },
    {
      "url": "https://apicatalog.oraclecloud.com/"
    },
    {
      "url": "{server}",
      "variables": {
        "server": {
          "default" : "https://apicatalog.oraclecloud.com/"
        }
      }
    }
  ],

Sample based on 'server templating' notes from https://swagger.io/docs/specification/api-host-and-base-path/

oas3-custom-url-alternate-option

In this sample, there is a lot of vertical space lost, as we are using a generic model, which can be used for more complex parameterized configuration.

We are also not able to see an option when there is no entry in the swagger for any default 'servers' value, meaning that we won't be able to gradually use this for new swagger documents without to rewrite the whole set we host today ~ 92 collections / 1200 unique Swagger documents.

Additional context

Relates to https://github.com/swagger-api/swagger-ui/issues/4292

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

No file, test, or entry point is named in the issue. Start by reviewing the existing Try It Out server-selection behavior and the related issue #4292, then compare it with the supplied OpenAPI servers examples. Done means users can enter a custom URL when no default exists and can choose or replace values without excessive screen space.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, openapi
Domain
api, frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.