fix: swapping out the $ref parsing engine of flattenSchema

[erunion]

🧰 What's being changed?

This completely swaps out the $ref parsing engine behind flattenSchema with json-schema-ref-parser to allow us to properly, easily, handle circular references without infinitely recusing them.

How it works is we'll funnel an incoming schema and API definition into json-schema-ref-parser to dereference it but allowing it to ignore circular refs. If a $ref is circular, it'll remain in the schema as $ref, enabling us to quickly detect and ignore circular refs when flattening a schema.

With this change, flattenSchema is now an async function.

[dok]

How does this work in conjunction with https://github.com/readmeio/react-jsonschema-form? Are they related?

I'm a little bit out of the loop on this one

[erunion]

@dok This is completely unrelated to that. This flattenSchema method is only utilized when we flatten a response schema.

Ideally we'd dereference these schemas before they're passed into the explorer from the beginning so we wouldn't need to have any $ref fetching or parsing at all, but we're ways away from there as it'll require some reconfiguration in our backend models and potentially how we're storing data.

[dok]

What would be the way we would detect whether a dereferenced object after this function call? Whether a $ref: String exists within the dereferenced object?

[dok]

NVM I see it now: https://github.com/readmeio/oas/pull/292/files#diff-204487ea7066d929383376809d6e70ea36310eca01a89b9ef90cc8e7d366f150R35

[erunion]

If $ref exists in derefSchema at all, then it's circular.

[dok]

Gotcha. Are there any other times where a $ref cannot be satisfied?

[erunion]

If it's an external ref (like a URL to another spec) it'll remain unsatisfied if it's inaccessible.

That said, we shouldn't be attempting to resolve external refs at this point in the application cycle so I'm going to add resolve.external: false into the options here to prevent that as well as a test for that.

[erunion]

Setting the type here to this is so that in the frontend it'll show up as:

[dok]

@erunion oh I see. Thanks for the clarification. Is this easier to work with than the isCyclic functionality? It does seem to have a similar format to that (it looks recursive).

[erunion]

@dok Yeah this work could likely be built into either our form module, or when we build up JSON Schema with tooling/lib/parametersToJsonSchema to do this resolving work then.

Reworking that is all is a much larger project though and should probably be done further up the stack so we aren't processing the same $ref n times.

[dok]

Pre-approving with this in mind

[dok]

@erunion looks good!