Lazy resolution

[shockey]

Description

Lazy resolution will allow us to handle larger API definitions more effectively in Swagger-UI.

We currently run entire API definitions through the Swagger-Client resolver when the definition is loaded into the UI. We can save a lot of effort by having the UI request resolved data as needed.

Conveniently, $ref usage is restricted in the Swagger and OpenAPI Specifications, so we can rely on having enough data to populate a list of operations and models without resolving anything, and only resolve things when users interact with the UI.

Plan

• Create specActions.requestResolution([...path])
• Create specSelectors.getResolvedSubtree([...path])
• New flow:
  • requestResolved ->
  • is resolved data cached in state?
    • yes? noop
    • no? async SwC.resolveIn ->
      • update resolved state ->
      • re-render with updated state through getResolvedSubtree
• Rework Models & Operations to request and consume resolved subtrees as needed
• Support Swagger-Editor lifecycle in modified rendering (invalidate and re-request resolved subtrees when the spec content updates)
• Move spec metadata out of resolved key, into a new meta key
• Stop resolving by default (will need to provide an example to folks who will continue relying on specResolved)
• Collapse models by default, so they don't need to be resolved until the user interacts with them

[heldersepu]

On the "Collapse model(s) by default" there are options to expand to a specific level

• http://petstore.swagger.io/?defaultModelExpandDepth=5&defaultModelRendering=model#/pet/getPetById
• http://petstore.swagger.io/?defaultModelsExpandDepth=9&filter=ModelsOnly

After this change we still can use that right?

[shockey]

@heldersepu, yes! the default has changed, each model in the models section will collapse by default (level 1 now means “display the container and name, but no content”); this is to avoid needing to do the work until the user expresses their intention to see the model.

how does that feel to you?

[heldersepu]

Sounds good.
But this default value still configurable, right? if not then the configuration page should be updated

[heldersepu]

I think this will address some of the slow loading I'm getting here:
http://petstore.swagger.io/?url=http://nhc-noaa.azurewebsites.net/swagger_ErliSoares.json&filter=_&defaultModelsExpandDepth=5

[shockey]

@heldersepu hopefully it will, however modifying the expand depth is going to negate a lot of the benefits 😉

[heldersepu]

ohhh I was thinking that the lazy load meant a visual delay...
...like some sort of animation expanding the models in a lazy way instead of waiting for the full rendered version

[shockey]

@heldersepu no worries! it's an ambiguous term 😄

here's a static build of the changes, you can try them out: http://devilish-coat.surge.sh/#/

[heldersepu]

Testing on your build:
http://devilish-coat.surge.sh/?url=http://nhc-noaa.azurewebsites.net/swagger_ErliSoares.json&filter=_&defaultModelsExpandDepth=0
that loads a faster than on the petstore
But if I increase the number to 5 it just crashes...

[shockey]

Yeah, I'm seeing that too. I'm playing with it locally, looks like there's a lot of redundant resolving going on with this definition - working on it now. Thanks for the heads up!

[heldersepu]

I was thinking that the expanding of the models could be on a timer and inside the timer we do something like:
document.getElementsByClassName("model-toggle collapsed")[0].click()

[shockey]

@heldersepu, I like the idea in theory, but the resolver would still be blocking the main thread, so the UI would lock up for a spell without the user initiating work through a click, which feels not-great.

The idea behind that, though (resolving sequentially) may be part of the solution for the spec you provided.

I've isolated the issue to two definitions: Reserva and Patrimonio. They're either massive, or preserving some type of circular structure, which is causing the thread to crash. I'm not sure if it's a size problem or a loop problem, since I'm getting an out-of-memory error, not a call stack size error.

Stay tuned!

[heldersepu]

I guess I have to read on resolvers and how they block the main thread...

But here is a more concrete example on my idea:
Let's start with the page:
http://devilish-coat.surge.sh/?url=http://nhc-noaa.azurewebsites.net/swagger_ErliSoares.json&filter=_&defaultModelsExpandDepth=1
That renders fast
Then open the browser Dev Tools and in the console paste the following:

function ExpandModel() {
	const o = document.getElementsByClassName("model-toggle collapsed")
	if (o.length > 0) {
		o[0].click()
		setTimeout(ExpandModel, 100);
	}
}

Then all we need to do is execute it ExpandModel() that will "slowly" and recursively expand all models without any visible blocking spells

[shockey]

@heldersepu gotcha! i'm partial to saying that triggering UI events programmatically would be creating more work then necessary for the UI, but feel free to open a discussion ticket, @webron may have an opinion 😄

Beyond that... I think I've ironed out the performance issues with the definition you've been looking at. Try this one, @heldersepu: https://halting-coat.surge.sh