Merge branch 'vnext' into main

Author: VisualBean

README.md

@@ -78,6 +78,48 @@ var stream = await httpClient.GetStreamAsync("master/examples/streetlights-kafka
 var asyncApiDocument = new AsyncApiStreamReader().Read(stream, out var diagnostic);
 ```
 
+#### Reading External $ref
+
+You can read externally referenced AsyncAPI documents by setting the `ReferenceResolution` property of the `AsyncApiReaderSettings` object to `ReferenceResolutionSetting.ResolveAllReferences` and providing an implementation for the `IAsyncApiExternalReferenceReader` interface. This interface contains a single method to which the built AsyncAPI.NET reader library will pass the location content contained in a `$ref` property (usually some form of path) and interface will return the content which is retrieved from wherever the `$ref` points to as a `string`. The AsyncAPI.NET reader will then automatically infer the `T` type of the content and recursively parse the external content into an AsyncAPI document as a child of the original document that contained the `$ref`. This means that you can have externally referenced documents that themselves contain external references. 
+
+This interface allows users to load the content of their external reference however and from whereever is required. A new instance of the implementor of `IAsyncApiExternalReferenceReader` should be registered with the `ExternalReferenceReader` property of the `AsyncApiReaderSettings` when creating the reader from which the `GetExternalResource` method will be called when resolving external references.
+
+Below is a very simple example of implementation for `IAsyncApiExternalReferenceReader` that simply loads a file and returns it as a string found at the reference endpoint.
+```csharp
+using System.IO;
+
+public class AsyncApiExternalFileSystemReader : IAsyncApiExternalReferenceReader
+{
+    public string GetExternalResource(string reference)
+    {
+        return File.ReadAllText(reference);
+    }
+}
+```
+
+This can then be configured in the reader as follows:
+```csharp
+var settings = new AsyncApiReaderSettings
+{
+  ReferenceResolution = ReferenceResolutionSetting.ResolveAllReferences,
+  ExternalReferenceReader = new AsyncApiExternalFileSystemReader(),
+};
+var reader = new AsyncApiStringReader(settings);
+```
+
+This would function for a AsyncAPI document with following reference to load the content of `message.yaml` as a `AsyncApiMessage` object inline with the document object.
+```yaml
+asyncapi: 2.3.0
+info:
+  title: test
+  version: 1.0.0
+channels:
+  workspace:
+    publish:
+      message:
+        $ref: "../../../message.yaml"
+```
+
 ### Bindings
 To add support for reading bindings, simply add the bindings you wish to support, to the `Bindings` collection of `AsyncApiReaderSettings`.
 There is a nifty helper to add different types of bindings, or like in the example `All` of them.

src/LEGO.AsyncAPI.Bindings/AMQP/AMQPOperationBinding.cs

@@ -5,7 +5,6 @@ namespace LEGO.AsyncAPI.Bindings.AMQP
     using System;
     using System.Collections.Generic;
     using LEGO.AsyncAPI.Models;
-    using LEGO.AsyncAPI.Readers;
     using LEGO.AsyncAPI.Readers.ParseNodes;
     using LEGO.AsyncAPI.Writers;
 

src/LEGO.AsyncAPI.Bindings/BindingsCollection.cs

@@ -45,7 +45,7 @@ public static TCollection Add<TCollection, TItem>(
             return destination;
         }
 
-        public static IEnumerable<IBindingParser<IBinding>> All => new List<IBindingParser<IBinding>>
+        public static ICollection<IBindingParser<IBinding>> All => new List<IBindingParser<IBinding>>
         {
             Pulsar,
             Kafka,
@@ -57,51 +57,51 @@ public static TCollection Add<TCollection, TItem>(
             MQTT,
         };
 
-        public static IEnumerable<IBindingParser<IBinding>> Http => new List<IBindingParser<IBinding>>
+        public static ICollection<IBindingParser<IBinding>> Http => new List<IBindingParser<IBinding>>
         {
             new HttpOperationBinding(),
             new HttpMessageBinding(),
         };
 
-        public static IEnumerable<IBindingParser<IBinding>> Websockets => new List<IBindingParser<IBinding>>
+        public static ICollection<IBindingParser<IBinding>> Websockets => new List<IBindingParser<IBinding>>
         {
             new WebSocketsChannelBinding(),
         };
 
-        public static IEnumerable<IBindingParser<IBinding>> Kafka => new List<IBindingParser<IBinding>>
+        public static ICollection<IBindingParser<IBinding>> Kafka => new List<IBindingParser<IBinding>>
         {
             new KafkaServerBinding(),
             new KafkaChannelBinding(),
             new KafkaOperationBinding(),
             new KafkaMessageBinding(),
         };
 
-        public static IEnumerable<IBindingParser<IBinding>> Pulsar => new List<IBindingParser<IBinding>>
+        public static ICollection<IBindingParser<IBinding>> Pulsar => new List<IBindingParser<IBinding>>
         {
             new PulsarServerBinding(),
             new PulsarChannelBinding(),
         };
 
-        public static IEnumerable<IBindingParser<IBinding>> Sqs => new List<IBindingParser<IBinding>>
+        public static ICollection<IBindingParser<IBinding>> Sqs => new List<IBindingParser<IBinding>>
         {
             new SqsChannelBinding(),
             new SqsOperationBinding(),
         };
 
-        public static IEnumerable<IBindingParser<IBinding>> Sns => new List<IBindingParser<IBinding>>
+        public static ICollection<IBindingParser<IBinding>> Sns => new List<IBindingParser<IBinding>>
         {
             new SnsChannelBinding(),
             new SnsOperationBinding(),
         };
 
-        public static IEnumerable<IBindingParser<IBinding>> AMQP => new List<IBindingParser<IBinding>>
+        public static ICollection<IBindingParser<IBinding>> AMQP => new List<IBindingParser<IBinding>>
         {
             new AMQPChannelBinding(),
             new AMQPOperationBinding(),
             new AMQPMessageBinding(),
         };
 
-        public static IEnumerable<IBindingParser<IBinding>> MQTT => new List<IBindingParser<IBinding>>
+        public static ICollection<IBindingParser<IBinding>> MQTT => new List<IBindingParser<IBinding>>
         {
             new MQTTServerBinding(),
             new MQTTOperationBinding(),

src/LEGO.AsyncAPI.Bindings/Http/HttpMessageBinding.cs

@@ -42,7 +42,7 @@ public override void SerializeProperties(IAsyncApiWriter writer)
         protected override FixedFieldMap<HttpMessageBinding> FixedFieldMap => new()
         {
             { "bindingVersion", (a, n) => { a.BindingVersion = n.GetScalarValue(); } },
-            { "headers", (a, n) => { a.Headers = JsonSchemaDeserializer.LoadSchema(n); } },
+            { "headers", (a, n) => { a.Headers = AsyncApiSchemaDeserializer.LoadSchema(n); } },
         };
     }
 }

src/LEGO.AsyncAPI.Bindings/Http/HttpOperationBinding.cs

@@ -63,7 +63,7 @@ public override void SerializeProperties(IAsyncApiWriter writer)
             { "bindingVersion", (a, n) => { a.BindingVersion = n.GetScalarValue(); } },
             { "type", (a, n) => { a.Type = n.GetScalarValue().GetEnumFromDisplayName<HttpOperationType>(); } },
             { "method", (a, n) => { a.Method = n.GetScalarValue(); } },
-            { "query", (a, n) => { a.Query = JsonSchemaDeserializer.LoadSchema(n); } },
+            { "query", (a, n) => { a.Query = AsyncApiSchemaDeserializer.LoadSchema(n); } },
         };
 
         public override string BindingKey => "http";

src/LEGO.AsyncAPI.Bindings/Kafka/KafkaMessageBinding.cs

@@ -67,7 +67,7 @@ public override void SerializeProperties(IAsyncApiWriter writer)
         protected override FixedFieldMap<KafkaMessageBinding> FixedFieldMap => new()
         {
             { "bindingVersion", (a, n) => { a.BindingVersion = n.GetScalarValue(); } },
-            { "key", (a, n) => { a.Key = JsonSchemaDeserializer.LoadSchema(n); } },
+            { "key", (a, n) => { a.Key = AsyncApiSchemaDeserializer.LoadSchema(n); } },
             { "schemaIdLocation", (a, n) => { a.SchemaIdLocation = n.GetScalarValue(); } },
             { "schemaIdPayloadEncoding", (a, n) => { a.SchemaIdPayloadEncoding = n.GetScalarValue(); } },
             { "schemaLookupStrategy", (a, n) => { a.SchemaLookupStrategy = n.GetScalarValue(); } },

src/LEGO.AsyncAPI.Bindings/Kafka/KafkaOperationBinding.cs

@@ -28,8 +28,8 @@ public class KafkaOperationBinding : OperationBinding<KafkaOperationBinding>
         protected override FixedFieldMap<KafkaOperationBinding> FixedFieldMap => new()
         {
             { "bindingVersion", (a, n) => { a.BindingVersion = n.GetScalarValue(); } },
-            { "groupId", (a, n) => { a.GroupId = JsonSchemaDeserializer.LoadSchema(n); } },
-            { "clientId", (a, n) => { a.ClientId = JsonSchemaDeserializer.LoadSchema(n); } },
+            { "groupId", (a, n) => { a.GroupId = AsyncApiSchemaDeserializer.LoadSchema(n); } },
+            { "clientId", (a, n) => { a.ClientId = AsyncApiSchemaDeserializer.LoadSchema(n); } },
         };
 
         /// <summary>

src/LEGO.AsyncAPI.Bindings/MQTT/LastWill.cs

@@ -2,9 +2,9 @@
 
 namespace LEGO.AsyncAPI.Bindings.MQTT
 {
+    using System;
     using LEGO.AsyncAPI.Models.Interfaces;
     using LEGO.AsyncAPI.Writers;
-    using System;
 
     public class LastWill : IAsyncApiElement
     {

src/LEGO.AsyncAPI.Bindings/MQTT/MQTTMessageBinding.cs

@@ -57,7 +57,7 @@ public override void SerializeProperties(IAsyncApiWriter writer)
         protected override FixedFieldMap<MQTTMessageBinding> FixedFieldMap => new()
         {
             { "payloadFormatIndicator", (a, n) => { a.PayloadFormatIndicator = n.GetIntegerValueOrDefault(); } },
-            { "correlationData", (a, n) => { a.CorrelationData = JsonSchemaDeserializer.LoadSchema(n); } },
+            { "correlationData", (a, n) => { a.CorrelationData = AsyncApiSchemaDeserializer.LoadSchema(n); } },
             { "contentType", (a, n) => { a.ContentType = n.GetScalarValue(); } },
             { "responseTopic", (a, n) => { a.ResponseTopic = n.GetScalarValue(); } },
         };

src/LEGO.AsyncAPI.Bindings/MQTT/MQTTOperationBinding.cs

@@ -3,9 +3,6 @@
 namespace LEGO.AsyncAPI.Bindings.MQTT
 {
     using System;
-    using System.Collections.Generic;
-    using LEGO.AsyncAPI.Models;
-    using LEGO.AsyncAPI.Readers;
     using LEGO.AsyncAPI.Readers.ParseNodes;
     using LEGO.AsyncAPI.Writers;