UX/DX: Support relative $refs, remote content loading from URL and open local folders

[ivangsa]

Current Limitations/Context

The current Studio web interface can not open local files or remote URLs, it only loads their content from a single file. Because it of this limitation it does not support relative references.

• Inability to edit local files and folders:
  • Users can only load one file at a time, edit it, and export it, with a prompt always required to specify the target file.
• Lack of support for relative references (e.g., $ref):
  • This is critical for teams using Kafka + Avro, where schemas are stored and referenced in external .avsc files.
• No support for loading remote files via links:
  • For example, a URL like https://studio.asyncapi.com?loadfile=http://github.com/user/repo/asyncapi.yml should load the specified file directly in Studio.

These limitations lead to a poor developer experience.

Proposal

The proposed changes are outlined in three stages:

Stage One:

1. Enable loading remote files directly from a URL.
2. Track the baseUrl of the loaded file and resolve relative references (e.g., $ref) using this baseUrl.

Stage Two:

1. When loading a local file with relative references, prompt the user for permission to access the containing folder using the File System Access API.

Stage Three:

1. Allow users to open local folders using the File System Access API with permission to read the folder.
2. Display a tree view of the opened local files in the left sidebar, above the API "Information" section.
3. Enable file selection from the tree view to load its contents in the editor. If the selected file is an AsyncAPI document, display its preview as well.

Impact: These changes will significantly enhance the user experience by improving file management and integration with external references.

Related to issue #528.

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[black-snow]

This is very much required. My real-life schemas have a lot of references. I don't see how I can reasonably use Studio without this for it won't even render.

[Shurtu-gal]

@ivangsa did you find a potential solution as last time we faced the same issue in #528.
Also FYI File System Access API is not available in firefox yet, so will it be breaking for them?

[ivangsa]

I don't find any technical blocker to implement this fully.
Combining Firefox + Safari gives approximately 17% of global users (2.23% + 14.75%) who definitely lack access to FileSystem Access which is unfortunately but +80% will benefit.
If the bounty gets approved I will implement it.

[Shurtu-gal]

Great that browsers now have support for this. Last time I was working on this, I had to implement a mock file system in browser and it was getting too complicated.

If can be completed, would definitely be a great addition.

[ivangsa]

@Shurtu-gal where can I find instructions to start studio localy in debug mode?

[Shurtu-gal]

What do you mean by debug mode?

[ivangsa]

Start studio in local environment, where I can place break points and inspect the execution for debuging..

[jerensl]

I think there still an issue with renaming and moving file in chrome here. FYI, here is the web platform test result for comparing support in the file system access across multiple browsers

There are also four issues listed in the specification but I believe 2 are worth considering before implementing this feature.
Issue 1: Access checks are currently tied to a "file system entry" which will be changed in the future as mention here
Issue 4: Implement blocking access for sensitive file as mention here

[ivangsa]

Thanks for the heads up, @jerensl.

There are three distinct stages described in this issue, and none of them are impacted by that limitation. Only stage three requires read access to the filesystem. Even if we extend this later with a potential stage four where users can save edited files, that too wouldn’t be blocked by it.

There’s a lot of value we can deliver already before hitting any of those blockers.