Enable External URL Support for AsyncAPI Files in Services Configuration

Use Case

I would like to propose an enhancement to the existing configuration of services in the EventCatalog, specifically regarding the integration with AsyncAPI files. Currently, the services property in the eventcatalog.config.api file only accepts local file paths for the AsyncAPI definitions (At least as far as I understand from the documentation and testing). Below is an example of the current configuration structure:

[
  '@eventcatalog/generator-asyncapi',
  {
    services: [
      { path: path.join(__dirname, 'asyncapi-files', 'new-uc-service.yml'), id: 'Client Service'},
    ],
    domain: { id: 'clients', name: 'Client', version: '0.0.1' },
    debug: true
  },
],

Proposed Enhancement: I would like to suggest extending this feature to allow referencing external AsyncAPI files via URLs (for example, https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0/examples/2.0.0/streetlights.yml). This feature would significantly improve collaboration and integration across teams.

Proposed Solution

User story suggestion Title: Allow External URL References for AsyncAPI Files in EventCatalog

Description: As an EventCatalog user, I want to reference AsyncAPI files through external URLs, so that different teams can easily collaborate and keep the event documentation always up-to-date without the need to copy files locally.

Acceptance Criteria:

The system should allow the path property in the services configuration to accept external URLs (e.g., files hosted on GitHub, or anyanother public URL, etc.).
When providing an external URL, EventCatalog should be able to fetch and process the AsyncAPI file just like it does with a local file.
The system should validate and return a clear error if the provided URL is invalid or inaccessible.

Implementation Notes

Possible Implementation Flow:

Detect if the path is a URL.
Make the HTTP request to fetch the file.
Process the file based on the format (YAML or JSON).
Validate the AsyncAPI file to ensure it is correct.
Integrate the AsyncAPI file into EventCatalog as is done with local files.
Handle errors like invalid or inaccessible URLs.

Conclusion: This approach will allow EventCatalog to be more flexible and enable easier collaboration between teams that manage AsyncAPI files in a decentralized manner, simplifying access to externally hosted files.

Community Notes

Please vote by adding a 👍 reaction to the issue to help us prioritize.
If you are interested to work on this issue, please leave a comment.
If this issue is labeled needs-discussion, it means the spec has not been finalized yet. Please reach out in the EventCatalog Discord.

Hello @Nayra-Neves & event-catalog community 👋,

the lack of this feature let to the situation at my former company, that we started creating tooling around syncing/pushing changed/updated spec files from any given repo in the central eventcatalog repo. While this approach worked, it required a lot of tooling around.

So I would also totally opt for having the ability, to link to existing files outside the catalog repo. I only see the challenge, that proper authn/authz needs to be put in place too, because in corporate environments you would never see private spec files sitting on the webs without auth.

What I would be interested in is, how this feature would be different when the event catalog actually would get a real backend, instead of being generator locally @boyney123 ?

If support on this issue is required, we can help ✌️

Cheers, Marvin

event-catalog / eventcatalog