refactor!: centralize reference resolution and implement specific reference types.

[VisualBean]

This pull request includes several important changes across multiple files in the LEGO.AsyncAPI project. The changes primarily focus on adding copyright notices, modifying namespace imports, and enhancing the AsyncApiDiagnostic class.

Closes: #196

Licensing and Namespace Updates:

• Added copyright notices:

  • src/LEGO.AsyncAPI.Bindings/Sns/Principal.cs
  • src/LEGO.AsyncAPI.Bindings/Sns/PrincipalObject.cs
  • src/LEGO.AsyncAPI.Bindings/Sns/PrincipalStar.cs
  • src/LEGO.AsyncAPI.Bindings/Sqs/PrincipalObject.cs
  • src/LEGO.AsyncAPI.Bindings/Sqs/PrincipalStar.cs

• Removed unnecessary using directive:

  • src/LEGO.AsyncAPI.Bindings/Sns/Statement.cs
  • src/LEGO.AsyncAPI.Bindings/Sqs/Statement.cs

Code Enhancements:

• Modified SnsOperationBinding class to use this.identifierFixFields:

  • src/LEGO.AsyncAPI.Bindings/Sns/SnsOperationBinding.cs

• Added Append method to AsyncApiDiagnostic class:

  • src/LEGO.AsyncAPI.Readers/AsyncApiDiagnostics.cs

Refactoring:

• Removed AsyncApiExternalReferenceResolver class:

  • src/LEGO.AsyncAPI.Readers/AsyncApiExternalReferenceResolver.cs (Fa207344R1)

• Refactored AsyncApiJsonDocumentReader to use instance context:

  • src/LEGO.AsyncAPI.Readers/AsyncApiJsonDocumentReader.cs [1] [2] [3] [4] [5] [6]

Reference implementations has changed

Changed References to be dereferenced through a 'workspace' type.
Resolved references are cached here for later, and referenced through the new reference types specifically.

private AsyncApiParameter Target
{
    get
    {
        this.target ??= this.Reference.Workspace.ResolveReference<AsyncApiParameter>(this.Reference);
        return this.target;
    }
}

public override string Description { get => this.Target?.Description; set => this.Target.Description = value; }

References are still resolved at read time however, due to constraints in how the project align with eachother.

The core Reference type, has been amended to return more 'correct' output, in terms of what used to be the 'Id' which in reality was supposed to be the fragment identifier.

External Reference resolution

External references will now be resolved, as many turtles down as is required.
The reference streams (original documents) are cached in the workspace, in case there are multiple fragmented references to them.
All external references are forced to json (from yaml) and json-pointers are used for fragment lookups.
This means that you can technically reference yaml documents from a json asyncapi document, and vice versa, but this should be seen more as a feature than anything else.

external uri's are expected to be prefixed with either file:// or http(s)://.
A custom StreamLoader can be implemented if something different is needed.
Stream output is expected to be yaml or json.

Fragments

Fragments are now fully resolved, across the document if needed - not just components.
this means that you can now reference other parts of the document if needed.
like this.

asyncapi: 2.3.0
info:
  title: test
  version: 1.0.0
channels:
  workspace:
    publish:
      message:
        title: test message
  other:
    $ref: "#/channels/workspace"

Fixes

This also fixes a few missing reference resolution paths;

• Bindings
• MessageTraits

---

BREAKING CHANGE:

References

References are now specific types that decorator the original type.
This means 2 things.

1. References are written directly instead of the type, rather than added to the original type.

Changed from

new AsyncApiOperationTrait()
{
    Reference = new AsyncApiReference()
    {
        FragmentId = "kafka",
        Type = ReferenceType.OperationTrait,
    },
},

To

new AsyncApiOperationTraitReference("#/components/operationTraits/kafka");

2. references are now fully qualified (rather than using the type as a weak reference, you must now write out where the reference is actually located.). (except for SecurityRequirements which still reference components through the scheme name rather than the components location.)

Renames

AvroSchema has been renamed to AsyncApiAvroSchema to denote the top level abstract as a specific AsyncApi Class.

Others

The concrete payload types has been removed, as these posed unneeded complexity for the library consumers.
Particularly with references.

Now the AsyncApiAvroSchema and AsyncApiJsonSchema types can be used directly as message payloads.