Skip to content

Commit 0b506e6

Browse files
authored
docs: Update README.md
1 parent e2fbdaf commit 0b506e6

File tree

1 file changed

+93
-62
lines changed

1 file changed

+93
-62
lines changed

README.md

Lines changed: 93 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -35,39 +35,72 @@ Main classes to know:
3535
### Writing
3636

3737
```csharp
38-
var myFirstAsyncApi = new AsyncApiDocument
39-
{
40-
Info = new AsyncApiInfo
41-
{
42-
Title = "my first asyncapi"
43-
},
44-
Channels = new Dictionary<string, AsyncApiChannel>
45-
{
46-
{
47-
"users", new AsyncApiChannel
48-
{
49-
Subscribe = new AsyncApiOperation
50-
{
51-
OperationId = "users",
52-
Description = "my users channel"
53-
}
54-
}
55-
}
56-
}
57-
};
58-
var yaml = myFirstAsyncApi.SerializeAsYaml();
59-
//asyncapi: '2.5.0'
38+
var myFirstAsyncApi = new AsyncApiDocument
39+
{
40+
Info = new AsyncApiInfo
41+
{
42+
Title = "my first asyncapi",
43+
},
44+
Channels = new Dictionary<string, AsyncApiChannel>
45+
{
46+
{
47+
"users", new AsyncApiChannel
48+
{
49+
Subscribe = new AsyncApiOperation
50+
{
51+
OperationId = "users",
52+
Description = "my users channel",
53+
Message = new List<AsyncApiMessage>
54+
{
55+
new AsyncApiMessageReference("#/components/messages/MyMessage"),
56+
},
57+
},
58+
}
59+
},
60+
},
61+
Components = new AsyncApiComponents
62+
{
63+
Messages = new Dictionary<string, AsyncApiMessage>
64+
{
65+
{
66+
"MyMessage", new AsyncApiMessage
67+
{
68+
Name = "Hello!",
69+
}
70+
},
71+
},
72+
},
73+
};
74+
75+
var yaml = myFirstAsyncApi.SerializeAsYaml(AsyncApi);
76+
77+
//asyncapi: 2.6.0
6078
// info:
6179
// title: my first asyncapi
62-
// channels:
63-
// users:
64-
// subscribe:
65-
// operationId: users
66-
// description: my users channel
80+
//channels:
81+
// users:
82+
// subscribe:
83+
// operationId: users
84+
// description: my users channel
85+
// message:
86+
// $ref: '#/components/messages/MyMessage'
87+
//components:
88+
// messages:
89+
// MyMessage:
90+
// name: Hello!
6791
```
6892

93+
6994
### Reading
7095

96+
There are 3 reader types
97+
1. AsyncApiStringReader
98+
2. AsyncApiTextReader
99+
3. AsyncApiStreamReader
100+
101+
All 3 supports both json and yaml.
102+
103+
#### StreamReader
71104
```csharp
72105
var httpClient = new HttpClient
73106
{
@@ -78,47 +111,45 @@ var stream = await httpClient.GetStreamAsync("master/examples/streetlights-kafka
78111
var asyncApiDocument = new AsyncApiStreamReader().Read(stream, out var diagnostic);
79112
```
80113

81-
#### Reading External $ref
114+
#### StringReader
115+
```csharp
116+
var yaml =
117+
"""
118+
asyncapi: 2.6.0
119+
info:
120+
title: my first asyncapi
121+
channels:
122+
users:
123+
subscribe:
124+
operationId: users
125+
description: my users channel
126+
message:
127+
$ref: '#/components/messages/MyMessage'
128+
components:
129+
messages:
130+
MyMessage:
131+
name: Hello!
132+
""";
133+
134+
var asyncApiDocument = new AsyncApiStringReader().Read(yaml, out var diagnostic);
135+
```
136+
All readers will write warnings and errors to the diagnostics.
82137

83-
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.
84138

85-
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.
139+
### Reference Resolution
140+
Internal references are resolved by default. This includes component and non-component references e.g `#/components/messages/MyMessage` and `#/servers/0`.
141+
External references can be resolved by setting `ReferenceResolution` to `ResolveAllReferences`.
142+
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`.
143+
External references are always force converted to Json during resolution. This means that both yaml and json is supported - but not other serialization languages.
86144

87-
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.
88145
```csharp
89-
using System.IO;
90-
91-
public class AsyncApiExternalFileSystemReader : IAsyncApiExternalReferenceReader
92-
{
93-
public string Load(string reference)
94-
{
95-
return File.ReadAllText(reference);
96-
}
97-
}
146+
var settings = new AsyncApiReaderSettings { ReferenceResolution = ReferenceResolution.ResolveAllReferences };
147+
var document = new AsyncApiStringReader(settings).Read(json, out var diagnostics);
98148
```
99149

100-
This can then be configured in the reader as follows:
101-
```csharp
102-
var settings = new AsyncApiReaderSettings
103-
{
104-
ReferenceResolution = ReferenceResolutionSetting.ResolveAllReferences,
105-
ExternalReferenceReader = new AsyncApiExternalFileSystemReader(),
106-
};
107-
var reader = new AsyncApiStringReader(settings);
108-
```
109150

110-
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.
111-
```yaml
112-
asyncapi: 2.3.0
113-
info:
114-
title: test
115-
version: 1.0.0
116-
channels:
117-
workspace:
118-
publish:
119-
message:
120-
$ref: "../../../message.yaml"
121-
```
151+
152+
Reference resolution can be disabled by setting `ReferenceResolution` to `DoNotResolveReferences`.
122153

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

133164
## Attribution

0 commit comments

Comments
 (0)