Referencing named schemas in the model view

[KevinMitchell]

Hi,

I think the styling of RapiDoc is excellent, particularly when using the dark theme. But there's one behavior that currently prevents me from using the viewer. In the model view the viewer currently expands out everything. So if we reference a schema multiple times each use seems to get inlined. Which makes the model view extremely verbose in some examples. Is there an option I haven't noticed that changes this behavior so we see the top-level model and below that the models for the named schemas it references?

I haven't tried an example with a recursive schema yet, but wouldn't this cause problems for the current approach of fully expanding the model?

Thanks Kevin

[mrin9]

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

[KevinMitchell]

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.

[KevinMitchell]

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?

[mrin9]

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