Reading

The AsyncApiReader is a component in the .NET library that can be used to deserialize AsyncAPI specifications from either JSON or YAML formats. The deserialized AsyncAPI document can then be manipulated in memory as a C# object.

Basic usage

To use any of the AsyncApiReaders, you first need to create an instance.

There are 3 types of readers, which all have the same API

1. AsyncApiStringReader
2. AsyncApiStreamReader
3. AsyncApiTextReader

To use any of the AsyncApiReaders, you first need to create an instance.

var reader = new AsyncApiStringReader();
var doc = reader.Read(yaml, out var diagnostic);

You can override default reader settings by passing in an AsyncApiReaderSettings object.

or overriding settings

var settings = new AsyncApiReaderSettings();
var reader = new AsyncApiStringReader(settings);

Diagnostics

When calling .Read() the reader will output any and all Diagnostics errors and warnings. These can be both from Serialization errors/warnings (if the specification is not proper json/yaml) or from validation errors/warnings

All diagnostic messages will contain a pointer to what failed, see example under ValidationRules

Settings

The settings object holds a few different settings that can be applied.

ReferenceResolution

You can use ReferenceResolutionSetting.DoNotResolveReferences to enforce not resolving references during deserialization. For more information see Reference Resolution

Extension parsers

Extension parsers enable you to transform extensions, in any way you want. See example below.

asyncapi: 2.3.0
info:
  title: test
  version: 1.0.0
  contact:  
    name: API Support
    url: https://www.example.com/support
    email: [email protected]
channels:
  workspace:
    x-someValue: onetwothreefour

Func<AsyncApiAny, IAsyncApiExtension> valueExtensionParser = (any) =>
{
    if (any.TryGetValue<string>(out var value))
    {
        if (value == "onetwothreefour")
        {
            return new AsyncApiAny(1234);
        }
    }

    return new AsyncApiAny("No value provided");
};

var settings = new AsyncApiReaderSettings
{
    ExtensionParsers = new Dictionary<string, Func<AsyncApiAny, IAsyncApiExtension>>
    {
        { "x-someValue", valueExtensionParser },
    },
};

var reader = new AsyncApiStringReader(settings);
var doc = reader.Read(yaml, out var diagnostic);
Assert.AreEqual(AsyncApiAny.FromExtensionOrDefault<int>(doc.Channels["workspace"].Extensions["x-someValue"]), 1234); // True

ValidationRules

Validation Rules can be added, to validate parts of the specification during reading, any errors/warnings will be pushed to the Diagnostics output of the reader.

as an example we could have the following validation rule for a License

var settings = new AsyncApiReaderSettings();
settings.RuleSet.Add(new ValidationRule<AsyncApiLicense>((context, item) =>
{
    context.Enter("name");
    if (item != null && item.Name != "MIT")
    {
        context.CreateError("license", "License MUST be MIT");
    }
    context.Exit();
}));

Given the following AsyncApi specification

asyncapi: 2.6.0
info:
  title: test
  version: 1.0.0
  license:
    name: apache
  contact:  
    name: API Support
    url: https://www.example.com/support
    email: [email protected]

Diagnostics will contain the following error message.