UX/DX: Support relative $refs, remote content loading from URL and open local folders #1224
Description
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
.avscfiles.
- This is critical for teams using Kafka + Avro, where schemas are stored and referenced in external
- No support for loading remote files via links:
- For example, a URL like
https://studio.asyncapi.com?loadfile=http://github.com/user/repo/asyncapi.ymlshould load the specified file directly in Studio.
- For example, a URL like
These limitations lead to a poor developer experience.
Proposal
The proposed changes are outlined in three stages:
Stage One:
- Enable loading remote files directly from a URL.
- Track the
baseUrlof the loaded file and resolve relative references (e.g.,$ref) using thisbaseUrl.
Stage Two:
- 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:
- Allow users to open local folders using the File System Access API with permission to read the folder.
- Display a tree view of the opened local files in the left sidebar, above the API "Information" section.
- 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.