SwaggerEditor@next: use stable version of @asyncapi/[email protected]

[char0n]

The goal of this issue is to use stable version of @asyncapi/[email protected]. Unfortunately this stable version started to use @asyncapi/[email protected] under the hood which now uses Spectral for validation and reference processing (let's call all these new versions AsyncAPI next gen). This introduced many issues documented below:

Issue 1

It's complicated to bundle Spectral. But, we've already did some work to be able to support it in our building infra: swagger-api/swagger-editor-cra@e7ebbca

The POC of integrating next gen AsyncAPI tooling with Spectral is here: #4446

Issue 2

Due to the fact that @asyncapi/[email protected] now uses Spectral, our bundle size have increased significantly. The parser also does the validation before parsing. We'll have to adapt to that and propagate validation errors to editor markers properly.

More info in asyncapi/parser-js#857

Issue 3

@asyncapi/[email protected] serialization and deserialization it broken when used with @asyncapi/[email protected]. This is essential for us to store parsed AsyncAPI documents in redux. It can be worked around as demonstrated in POC #4446.

More info in: asyncapi/asyncapi-react#769

Issue 4

There is a breaking change in how @asyncapi/[email protected] handles references.

In Parser v1 we use @apidevtools/json-schema-ref-parser and now I see that v2 uses @stoplight/json-ref-resolver which is marked as deprecated and points to @apidevtools/json-schema-ref-parser 😄

We do provide override for AsyncAPI definition parsing which allows to plugin custom logic of URL resolution - https://github.com/swagger-api/swagger-editor/blob/718b04d756d0becc8bada052fbdcd960b7d8d51c/src/plugins/editor-preview-asyncapi/actions.js#L56-L55. It's critical that it functions equivalently.

It seems that the goal of AsyncAPI team is to return back to @apidevtools/json-schema-ref-parser, so it doesn't make sense for us to change own custom resolution mechanism, just to change it back again when the underlying library is switched.

More info in: asyncapi/parser-js#761

Here is example how to do override for spectral ref resolver: https://github.com/backstage/backstage/pull/22160/files

---

For now, we'll stick with last working version of @asyncapi/[email protected] with @asyncapi/[email protected].

[char0n]

For now we, we'll stick with last working version of @asyncapi/[email protected] with @asyncapi/[email protected].

This has been addressed in #4586

[char0n]

All issues have been addressed in #4446

Issue 1

swagger-editor-cra has been compensated to support Spectral and SwaggerEditor@5 provides instructions for webpack how to overcome Spectral bundling issues.

Issue 2

There is nothing we can do about this. As mentioned in various in AsyncAPI issues, this is the status quo that will stay with AsyncAPI tooling for some time.

Issue 3

Workaround has been utilized.

Issue 4

It's a breaking change. We'll document migration of parser option in release notes.