Skip to content

Commit

Permalink
docs: Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@VisualBean
VisualBean authored Jan 31, 2025
1 parent e2fbdaf commit 0b506e6
Showing 1 changed file with 93 additions and 62 deletions.
155 changes: 93 additions & 62 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,39 +35,72 @@ Main classes to know:
### Writing

```csharp
var myFirstAsyncApi = new AsyncApiDocument
{
Info = new AsyncApiInfo
{
Title = "my first asyncapi"
},
Channels = new Dictionary<string, AsyncApiChannel>
{
{
"users", new AsyncApiChannel
{
Subscribe = new AsyncApiOperation
{
OperationId = "users",
Description = "my users channel"
}
}
}
}
};
var yaml = myFirstAsyncApi.SerializeAsYaml();
//asyncapi: '2.5.0'
var myFirstAsyncApi = new AsyncApiDocument
{
Info = new AsyncApiInfo
{
Title = "my first asyncapi",
},
Channels = new Dictionary<string, AsyncApiChannel>
{
{
"users", new AsyncApiChannel
{
Subscribe = new AsyncApiOperation
{
OperationId = "users",
Description = "my users channel",
Message = new List<AsyncApiMessage>
{
new AsyncApiMessageReference("#/components/messages/MyMessage"),
},
},
}
},
},
Components = new AsyncApiComponents
{
Messages = new Dictionary<string, AsyncApiMessage>
{
{
"MyMessage", new AsyncApiMessage
{
Name = "Hello!",
}
},
},
},
};

var yaml = myFirstAsyncApi.SerializeAsYaml(AsyncApi);

//asyncapi: 2.6.0
// info:
// title: my first asyncapi
// channels:
// users:
// subscribe:
// operationId: users
// description: my users channel
//channels:
// users:
// subscribe:
// operationId: users
// description: my users channel
// message:
// $ref: '#/components/messages/MyMessage'
//components:
// messages:
// MyMessage:
// name: Hello!
```


### Reading

There are 3 reader types
1. AsyncApiStringReader
2. AsyncApiTextReader
3. AsyncApiStreamReader

All 3 supports both json and yaml.

#### StreamReader
```csharp
var httpClient = new HttpClient
{
Expand All @@ -78,47 +111,45 @@ var stream = await httpClient.GetStreamAsync("master/examples/streetlights-kafka
var asyncApiDocument = new AsyncApiStreamReader().Read(stream, out var diagnostic);
```

#### Reading External $ref
#### StringReader
```csharp
var yaml =
"""
asyncapi: 2.6.0
info:
title: my first asyncapi
channels:
users:
subscribe:
operationId: users
description: my users channel
message:
$ref: '#/components/messages/MyMessage'
components:
messages:
MyMessage:
name: Hello!
""";

var asyncApiDocument = new AsyncApiStringReader().Read(yaml, out var diagnostic);
```
All readers will write warnings and errors to the diagnostics.

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.
### Reference Resolution
Internal references are resolved by default. This includes component and non-component references e.g `#/components/messages/MyMessage` and `#/servers/0`.
External references can be resolved by setting `ReferenceResolution` to `ResolveAllReferences`.
The default implementation will resolve anything prefixed with `file://`, `http://` & `https://`, however a custom implementation can be made, by inhereting from the `IStreamLoader` interface and setting the `ExternalReferenceLoader` in the `AsyncApiReaderSettings`.
External references are always force converted to Json during resolution. This means that both yaml and json is supported - but not other serialization languages.

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 Load(string reference)
{
return File.ReadAllText(reference);
}
}
var settings = new AsyncApiReaderSettings { ReferenceResolution = ReferenceResolution.ResolveAllReferences };
var document = new AsyncApiStringReader(settings).Read(json, out var diagnostics);
```

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"
```

Reference resolution can be disabled by setting `ReferenceResolution` to `DoNotResolveReferences`.

### Bindings
To add support for reading bindings, simply add the bindings you wish to support, to the `Bindings` collection of `AsyncApiReaderSettings`.
Expand All @@ -127,7 +158,7 @@ There is a nifty helper to add different types of bindings, or like in the examp
```csharp
var settings = new AsyncApiReaderSettings();
settings.Bindings = BindingsCollection.All;
var asyncApiDocument = new AsyncApiStringReader(settings).Read(stream, out var diagnostic);
var asyncApiDocument = new AsyncApiStringReader(settings).Read(yaml, out var diagnostic);
```

## Attribution
Expand Down

0 comments on commit 0b506e6

Please sign in to comment.