swagger-api / swagger-api/swagger-ui

feature: dynamic schema/server response viewer

Open
#4,372 11 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Q A
Bug or feature request? feature
Which Swagger/OpenAPI version? 2.0
Which Swagger-UI version? 3.latest
How did you install Swagger-UI? n/a
Which browser & version? n/a
Which operating system? n/a
Current Behavior

Currently, the "Example Value" and "Server response" display section in swagger-ui 3.x are just static canvas, which works very well for small examples, for both schema, intended response (examples), and server responses.

For API's that have large inputs and/or large outputs, or for users with relatively low-resolution screens, this doesn't scale well for them

Possible Solution

We've been working on a react based replacement for our swagger-ui 2.1.4 implementation within our product; however, we're currently changing direction to baseline this as an upgrade from 2.1.4 to 3.x, and would like to port in some of the features that we've added.

Specifically for this feature request, we've built a dynamic schema/server response viewer, that has the following characteristics:

  1. Great line/section copy to clipboard method, with both the inline copy (which copies either the single line or if done at a tree head, copies that section of the tree). Also has a fancy "copy" animation checkmark
  2. Great formatting and stylization, Line numbers, collapsible trees, nicely stylized like common editors (like sublime text, etc)
  3. Ability to take response viewer into a full-screen mode with a single click, to really dig into big responses easily, WITHOUT taking them to an external JSON parser or external tool
  4. Great "show" function, where it unfolds the JSON just a little bit and tells you how many subitems are in the tree. This is VERY useful for API's that have VERY big schemas/server responses

This would replace the "Example Value" display section in swagger-ui 3 for schema and responses, which is just a static canvas now, AND should also replace the "Response body" section when using the Try It Out method.

Screenshots

I've included a few screenshots from the internal code that we have.

Posting this here to garner feedback, so that we can shape this for optimal upstream acceptance once we're done.

screenshot 2018-03-22 02 33 45 screenshot 2018-03-22 02 36 33 screenshot 2018-03-22 02 36 42 screenshot 2018-03-22 02 42 39

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 reviewing the current Example Value, Server response, and Try It Out response-body entry points in Swagger UI, using the supplied screenshots to understand the proposed interaction. Done would mean a dynamic viewer with collapsible trees, line numbers, section or line copying, full-screen mode, and compact expansion for large schemas and responses.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.