swagger-api / swagger-api/swagger-ui

How to render "Select a spec" only when needed?

Open
#4,328 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

cat: rendering type: enhancement
Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Wondering if there is a way to handle displaying the drop down field to select a spec only when needed - by that, I mean there is more than one value to chose from.

Related question - could we merge the content of scheme-container and global-server-container into a single region of the page?

Today, with our integration of Swagger UI 3 to support OpenAPI 3 content, we always get the dropdown rendered, even when the API is a single document.

We do this by passing the urls array with one entry into the swagger at startup:
self.swaggerUi = SwaggerUIBundle({
dom_id: '#swaggerui', urls: urls, ...

Q A
Bug or feature request? Support more than a bug
Which Swagger/OpenAPI version? Swagger 2.0
Which Swagger-UI version? 3.12.0
How did you install Swagger-UI? webjar
Which browser & version? Chrome 65
Which operating system? Mac OS-X
Demonstration API definition

Sample API: https://apicatalog.oraclecloud.com/ui/views/swaggerui3/oracle-public/odx-oke/1.0

Expected Behavior

The main goal here is to try limiting the vertical space used by the header section of the UI so we can have more of the content visible without to require vertical scrolling

Current Behavior

Display a drop-down with a single value to select from

Possible Solution

Maybe the only question here is to figure out if this is the kind of customization that make sense to be done on the base, or if this is where we have to go our own way and replace the default region of the page with a custom version?

Context

apic-sample-openapi3-look-and-feel

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 at the SwaggerUIBundle initialization that passes the urls array, and compare the provided demonstration API with the current header layout. Determine how the UI decides whether to render the spec selector and whether scheme-container and global-server-container can share one region. Done means a single-document API does not show a redundant dropdown and the requested header-space behavior is addressed.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.