Comments (4)
Every OpenAPI renderers display information in its own opinionated ways.
For instance Swagger-UI's and ReDoc's default schema style is to display first level of attributes and there after you must click and expand, which in our survey of usability has been shown as a pain point. Most participants wanted the schema to be fully expanded to avoid multiple clicks to reveal.
So we took the opposite way as our primary approach, If it feels a bit verbose you can always click on the brackets and collapse them.
It is smart enough to figure out circular references, you may open any of our demos/example and try it with https://mrin9.github.io/RapiDoc/specs/circular.yaml and check how it handles it
I am guessing the way you want to organize your schema is to provide a link to the sub-schemas something what shins does
I hate the fact that a feature of RapiDoc is preventing you from using it, but I am sorry to say that I dont see us doing any work on changing the schema display style that you are looking for.
But we will shortly be introducing an option that allows you to control the depth of schema expansion, that way help a bit with verbosity issue that you are facing
from rapidoc.
Thanks for the clarification of your strategy. Personally I think both approaches have their place. There are (at least) two very different reasons for breaking a schema into multiple schemas inked via references. The first, and perhaps most common case, is where you just want to split a large schema into multiple sections, where each “sub-schema” is often just referenced once, and doesn’t necessarily represent a clear semantic type. In this schenario the current approach, that simply expands out the subschemas, makes sense.
In other cases some schemas represent a clear semantic type, such as “Person”, that may be referenced multiple times from other parts of the specification. In this scenario I’d argue that hiding such sub-schemas decreases the readability of the specification. Because we can no longer “understand” a type like “Person” once. Each separate “reference” to such a schema is always expanded out, and we have to work harder to see which subtrees represent a Person rather than something else. And the problem becomes even more accute when the same schema is references from multiple endpoints.
Whilst being able to control the level of expansion, as you suggested, might be useful, this won’t really help in such cases. As the referenced schemas are not displayed independently, when you collapse a subtree you have no way of showing what’s “inside” the collapsed subtree,. And so you end up having to guess the schema from the property name. Whereas being able to display “Person” inside the collapsed {} brackets would seem a lot more useful.
Of course ideally it would be good to be able to support both approaches in a natural fashion. I wonder how well it would work if we distinguished between schemas that were referenced multiple times in an API and those that were referenced just once. And used this to control when to display named schemas and when to treat them as “anonymous”?
But of course I realise there are many different types of API, and it’s hard to build a viewer that handles all cases equally well. And so it sounds like I might be trying to use RapiDoc for a style of API it's not really intended for.
from rapidoc.
You already provide the ability to control whether footers etc are displayed. So perhaps a hybrid approach might be to allow a "schema footer" to be optionally displayed containing the specifications of any schemas with multiple references. And then when you collapse a subtree you could display the name of the schema instead of just {}? That way the current behaviour would remain the same. But when someone optionally enables the "shared schemas" footer then the collapsed representation of a subtree would display the schema name. That behaviour, in conjunction with the ability to define the default expansion level, might work well?
from rapidoc.
Well, we lose all the schema-names/reference-names when we load the spec, we dereference it. All the refs
are replaced with the referenced object
(except those with circular references).
So a hybrid approach that you are suggesting will create a lot of churn in the code-base. I do not think we have that kind of bandwidth. But I will discuss this with our usability team, let see if they can come up with any cheap solution to this
For now I will be closing this issue
from rapidoc.
Related Issues (20)
- Field column for schema-style = "table" is too narrow drops name completely when collapsed
- Provide support for encoded (Content-Disposition) header
- Links part
- Array input examples ignore global fill-request-fields-with-example setting HOT 1
- Feature Request: Ability to Sort Properties HOT 1
- Authentication should hide token inputs when TRY is disabled
- Unable to grab js file from unpkg HOT 2
- No indication of which properties are required within a request body schema
- Schema tab should be shown before examples tab when schema is default
- Action buttons below request body table should only be shown when examples tab selected
- Content type should be indicated in consistent place for request body and response HOT 2
- Scroll Y Offset when scrolling to element
- Don't use description for sidebar title? HOT 1
- Font rendering is different in examples HOT 2
- Hard to distinguish between Basic Auth and Bearer auth HOT 1
- Clicking Auth end-point button fail to scroll to Auth section
- Trailing / added to curl examples HOT 1
- null example value leads to incorrect example JSON
- Retain auth on browser refresh HOT 4
- In 'focused' view, components still show up all on one page, causes hang HOT 4
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from rapidoc.