swagger-api / swagger-api/swagger-ui
Provide an easy way to enter custom URL to try-it feature
Nobody has claimed this yet.
- 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):
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/
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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