Implement Async API specification v3.0.0

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,5 @@
+**What this PR does**:
+<!-- Brief description of your PR / Short summary of the discussion or issue -->
+
+**Additional information:**
+<!-- Optional -->

.github/workflows/build-and-test.yml

@@ -16,7 +16,7 @@ jobs:
     - name: Setup .NET
       uses: actions/setup-dotnet@v3
       with:
-        dotnet-version: 8.0.x
+        dotnet-version: 9.0.x
     - name: Restore dependencies
       run: dotnet restore
     - name: Build

.github/workflows/publish.yml

@@ -14,7 +14,7 @@ jobs:
     - name: Setup .NET
       uses: actions/setup-dotnet@v3
       with:
-        dotnet-version: 8.0.x
+        dotnet-version: 9.0.x
     - name: Restore dependencies
       run: dotnet restore
     - name: Build

Neuroglia.AsyncApi.sln

@@ -31,6 +31,24 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "StreetLightsApi", "samples\
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Neuroglia.AsyncApi.AspNetCore", "src\Neuroglia.AsyncApi.AspNetCore\Neuroglia.AsyncApi.AspNetCore.csproj", "{9FF8A714-BFBF-4A09-87E4-57CEF088BFA7}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = ".github", ".github", "{4A936028-09D1-4ACD-8383-5B496DAB2E16}"
+	ProjectSection(SolutionItems) = preProject
+		.github\PULL_REQUEST_TEMPLATE.md = .github\PULL_REQUEST_TEMPLATE.md
+	EndProjectSection
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "ISSUE_TEMPLATE", "ISSUE_TEMPLATE", "{1FB272DF-4FE6-4417-B927-98DD5A821EC0}"
+	ProjectSection(SolutionItems) = preProject
+		.github\ISSUE_TEMPLATE\bug.yml = .github\ISSUE_TEMPLATE\bug.yml
+		.github\ISSUE_TEMPLATE\config.yml = .github\ISSUE_TEMPLATE\config.yml
+		.github\ISSUE_TEMPLATE\feature.yml = .github\ISSUE_TEMPLATE\feature.yml
+	EndProjectSection
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{90558701-3CBE-40D6-8E4D-A6A059C51213}"
+	ProjectSection(SolutionItems) = preProject
+		LICENSE = LICENSE
+		README.md = README.md
+	EndProjectSection
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -97,6 +115,7 @@ Global
 		{A139028A-50B1-4D62-B9A9-2D0CD438E2B0} = {4B933DF9-CD24-44B1-AF64-0D5E75B9AB45}
 		{3A707FE1-4AA3-4232-9E7D-88376580EAD5} = {D5DC0A71-F39C-4AA1-A284-66E622868D47}
 		{9FF8A714-BFBF-4A09-87E4-57CEF088BFA7} = {4B933DF9-CD24-44B1-AF64-0D5E75B9AB45}
+		{1FB272DF-4FE6-4417-B927-98DD5A821EC0} = {4A936028-09D1-4ACD-8383-5B496DAB2E16}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {DC433DEB-01E5-4328-B0BB-6FFFE8C7363F}

README.md

@@ -3,46 +3,49 @@
 ## Contents
 
 - [Neuroglia AsyncAPI](#neuroglia-asyncapi)
-  - [Contents](#contents)
-  - [Summary](#summary)
-  - [Status](#status)
-  - [Installation](#installation)
-      - [Core library](#core-library)
-      - [Fluent validation library](#fluent-validation-library)
-      - [Fluent builders library](#fluent-builders-library)
-      - [Input/Output library](#inputoutput-library)
-      - [Code-first generation library](#code-first-generation-library)
-      - [Dependency inject extensions library](#dependency-inject-extensions-library)
-      - [Cloud event extensions library](#cloud-event-extensions-library)
-      - [AsyncAPI document serving library](#asyncapi-document-serving-library)
-      - [AsyncAPI UI](#asyncapi-ui)
-  - [Usage](#usage)
+  + [Contents](#contents)
+  + [Summary](#summary)
+  + [Status](#status)
+  + [Installation](#installation)
+    - [Core library](#core-library)
+    - [Fluent validation library](#fluent-validation-library)
+    - [Fluent builders library](#fluent-builders-library)
+    - [Input/Output library](#inputoutput-library)
+    - [Code-first generation library](#code-first-generation-library)
+    - [Dependency inject extensions library](#dependency-inject-extensions-library)
+    - [Cloud event extensions library](#cloud-event-extensions-library)
+    - [AsyncAPI document serving library](#asyncapi-document-serving-library)
+    - [AsyncAPI UI](#asyncapi-ui)
+  + [Usage](#usage)
     - [Building an AsyncAPI Document](#building-an-asyncapi-document)
+      + [AsyncAPI v2](#asyncapi-v2)
+      + [AsyncAPI v3](#asyncapi-v3)
     - [Writing an AsyncAPI Document](#writing-an-asyncapi-document)
     - [Reading an AsyncAPI document](#reading-an-asyncapi-document)
     - [Generating code-first AsyncAPI documents](#generating-code-first-asyncapi-documents)
-      - [1. Mark your services with adequate attributes](#1-mark-your-services-with-adequate-attributes)
-      - [2.1. Generating documents manually](#21-generating-documents-manually)
-      - [2.2. Generating documents automatically and serve them using ASP](#22-generating-documents-automatically-and-serve-them-using-asp)
+      + [AsyncAPI v2](#asyncapi-v2-1)
+      + [AsyncAPI v3](#asyncapi-v3-1)
+    - [Generating documents manually](#21-generating-documents-manually)
+    - [Generating documents automatically and serve them using ASP](#22-generating-documents-automatically-and-serve-them-using-asp)
     - [Using the AsyncAPI UI](#using-the-asyncapi-ui)
-  - [Samples](#samples)
+  + [Samples](#samples)
     - [Streetlights API - Server](#streetlights-api---server)
 
 ## Summary
-A .NET used to visualize and interact with [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/v2.6.0) documents. The UI is built using Razor Pages and Boostrap
+A .NET used to visualize and interact with [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/v3.0.0) documents. The UI is built using Razor Pages and Boostrap
 
 ## Status
-`Microsoft.NET.Sdk.Web`
+
 | Name | Description | Latest Release | Spec version |
-| :---: | :---: | :---: | :---: |
-| [Neuroglia.AsyncApi.Core](https://www.nuget.org/packages/Neuroglia.AsyncApi.Core) | Contains `AsyncAPI` models and core services such as fluent builders, validators, reader, writer and code-first generator | [2.6.3](https://github.com/neuroglia-io/asyncapi/releases/tag/v2.6.3) | [v2.6.0](https://www.asyncapi.com/docs/reference/specification/v2.6.0) |
-| [Neuroglia.AsyncApi.Validation](https://www.nuget.org/packages/Neuroglia.AsyncApi.Validation) | Contains services to validate `AsyncAPI` documents | [2.6.3](https://github.com/neuroglia-io/asyncapi/releases/tag/v2.6.3) | [v2.6.0](https://www.asyncapi.com/docs/reference/specification/v2.6.0) |
-| [Neuroglia.AsyncApi.IO](https://www.nuget.org/packages/Neuroglia.AsyncApi.IO) | Contains services to read and write `AsyncAPI` documents | [2.6.3](https://github.com/neuroglia-io/asyncapi/releases/tag/v2.6.3) | [v2.6.0](https://www.asyncapi.com/docs/reference/specification/v2.6.0) |
-| [Neuroglia.AsyncApi.Generation](https://www.nuget.org/packages/Neuroglia.AsyncApi.Generation) | Contains extensions and services for code-first generation of `AsyncAPI` documents | [2.6.3](https://github.com/neuroglia-io/asyncapi/releases/tag/v2.6.3) | [v2.6.0](https://www.asyncapi.com/docs/reference/specification/v2.6.0) |
-| [Neuroglia.AsyncApi.CloudEvents](https://www.nuget.org/packages/Neuroglia.AsyncApi.CloudEvents) | Contains fluent extensions to build Cloud Event messages | [2.6.3](https://github.com/neuroglia-io/asyncapi/releases/tag/v2.6.3) | [v2.6.0](https://www.asyncapi.com/docs/reference/specification/v2.6.0) |
-| [Neuroglia.AsyncApi.ServiceDependencyExtensions](https://www.nuget.org/packages/Neuroglia.AsyncApi.ServiceDependencyExtensions) | Contains extensions to configure and register `AsyncAPI` services using dependency injection | [2.6.3](https://github.com/neuroglia-io/asyncapi/releases/tag/v2.6.3) | [v2.6.0](https://www.asyncapi.com/docs/reference/specification/v2.6.0) |
-| [Neuroglia.AsyncApi.AspNetCore](https://www.nuget.org/packages/Neuroglia.AsyncApi.AspNetCore) | Contains an `ASP.NET` middleware used to serve `AsyncAPI` documents | [2.6.3](https://github.com/neuroglia-io/asyncapi/releases/tag/v2.6.3) | [v2.6.0](https://www.asyncapi.com/docs/reference/specification/v2.6.0) |
-| [Neuroglia.AsyncApi.AspNetCore.UI](https://www.nuget.org/packages/Neuroglia.AsyncApi.AspNetCore.UI) | Contains the Razor Pages based UI for exploring `AsyncAPI` documents | [2.6.3](https://github.com/neuroglia-io/asyncapi/releases/tag/v2.6.3) | [v2.6.0](https://www.asyncapi.com/docs/reference/specification/v2.6.0) |
+|:------|:------------|:--------------:|:------------:|
+| [Neuroglia.AsyncApi.Core](https://www.nuget.org/packages/Neuroglia.AsyncApi.Core) | Contains `AsyncAPI` models and core services such as fluent builders, validators, reader, writer and code-first generator | [3.0.0](https://github.com/neuroglia-io/asyncapi/releases/tag/v3.0.0) | [v3.0.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0) |
+| [Neuroglia.AsyncApi.Validation](https://www.nuget.org/packages/Neuroglia.AsyncApi.Validation) | Contains services to validate `AsyncAPI` documents | [3.0.0](https://github.com/neuroglia-io/asyncapi/releases/tag/v3.0.0) | [v3.0.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0) |
+| [Neuroglia.AsyncApi.IO](https://www.nuget.org/packages/Neuroglia.AsyncApi.IO) | Contains services to read and write `AsyncAPI` documents | [3.0.0](https://github.com/neuroglia-io/asyncapi/releases/tag/v3.0.0) | [v3.0.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0) |
+| [Neuroglia.AsyncApi.Generation](https://www.nuget.org/packages/Neuroglia.AsyncApi.Generation) | Contains extensions and services for code-first generation of `AsyncAPI` documents | [3.0.0](https://github.com/neuroglia-io/asyncapi/releases/tag/v3.0.0) | [v3.0.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0) |
+| [Neuroglia.AsyncApi.CloudEvents](https://www.nuget.org/packages/Neuroglia.AsyncApi.CloudEvents) | Contains fluent extensions to build Cloud Event messages | [3.0.0](https://github.com/neuroglia-io/asyncapi/releases/tag/v3.0.0) | [v3.0.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0) |
+| [Neuroglia.AsyncApi.ServiceDependencyExtensions](https://www.nuget.org/packages/Neuroglia.AsyncApi.ServiceDependencyExtensions) | Contains extensions to configure and register `AsyncAPI` services using dependency injection | [3.0.0](https://github.com/neuroglia-io/asyncapi/releases/tag/v3.0.0) | [v3.0.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0) |
+| [Neuroglia.AsyncApi.AspNetCore](https://www.nuget.org/packages/Neuroglia.AsyncApi.AspNetCore) | Contains an `ASP.NET` middleware used to serve `AsyncAPI` documents | [3.0.0](https://github.com/neuroglia-io/asyncapi/releases/tag/v3.0.0) | [v3.0.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0) |
+| [Neuroglia.AsyncApi.AspNetCore.UI](https://www.nuget.org/packages/Neuroglia.AsyncApi.AspNetCore.UI) | Contains the Razor Pages based UI for exploring `AsyncAPI` documents | [3.0.0](https://github.com/neuroglia-io/asyncapi/releases/tag/v3.0.0) | [v3.0.0](https://www.asyncapi.com/docs/reference/specification/v3.0.0) |
 
 ## Installation
 
@@ -95,7 +98,9 @@ dotnet add package Neuroglia.AsyncApi.AspNetCore.UI
 
 ## Usage
 
-### Building an AsyncAPI Document
+### Building an AsyncAPI document
+
+#### AsyncAPI v2
 
 ```csharp
 var services = new ServiceCollection();
@@ -152,7 +157,13 @@ var document = builder
     .Build();
 ```
 
-### Writing an AsyncAPI Document 
+#### AsyncAPI V3
+
+```csharp
+
+```
+
+### Writing an AsyncAPI document 
 
 ```csharp
 var writer = serviceProvider.GetRequiredService<IAsyncApiDocumentWriter>();
@@ -169,17 +180,17 @@ var asyncApi = await reader.ReadAsync(stream, cancellationToken);
 
 ### Generating code-first AsyncAPI documents
 
-#### 1. Mark your services with adequate attributes
+#### AsyncAPI V2
 
 ```csharp
-[AsyncApi("Streetlights API", "1.0.0", Description = "The Smartylighting Streetlights API allows you to remotely manage the city lights.", LicenseName = "Apache 2.0", LicenseUrl = "https://www.apache.org/licenses/LICENSE-2.0")]
+[AsyncApiV2("Streetlights API", "1.0.0", Description = "The Smartylighting Streetlights API allows you to remotely manage the city lights.", LicenseName = "Apache 2.0", LicenseUrl = "https://www.apache.org/licenses/LICENSE-2.0")]
 public class StreetLightsService
   : BackgroundService
 {
 
   ... //Omitted for brevity
 
-  [Channel("light/measured"), PublishOperation(OperationId = "onLightMeasured", Summary = "Inform about environmental lighting conditions for a particular streetlight")]
+  [ChannelV2("light/measured"), PublishOperation(OperationId = "onLightMeasured", Summary = "Inform about environmental lighting conditions for a particular streetlight")]
   public async Task PublishLightMeasured(LightMeasuredEvent e)
   {
       MqttApplicationMessage message = new()
@@ -191,7 +202,7 @@ public class StreetLightsService
       await this.MqttClient.PublishAsync(message);
   }
 
-  [Channel("light/measured"), SubscribeOperation(OperationId = "lightMeasuredEvent", Summary = "Inform about environmental lighting conditions for a particular streetlight")]
+  [ChannelV2("light/measured"), SubscribeOperation(OperationId = "lightMeasuredEvent", Summary = "Inform about environmental lighting conditions for a particular streetlight")]
   protected async Task OnLightMeasured(LightMeasuredEvent e)
   {
       this.Logger.LogInformation($"Event received:{Environment.NewLine}{await this.Serializer.SerializeAsync(e)}");
@@ -204,19 +215,29 @@ public class StreetLightsService
 
 Note the usage of the following attributes:
 
-- `AsyncApi`: Marks a class for code-first `AsyncAPI` document generation. Used to provide information about the API (licensing, contact, ...)
-- `Channel`: Marks a method or class for code-first `AsyncAPI` channel generation. Used to provide information about the channel marked methods belong to.
-- `Operation`: Marks a method for code-first `AsyncAPI` operation generation. Use to provide information about the `AsyncAPI` operation.
+- `AsyncApiV2`: Marks a class for code-first `AsyncAPI` document generation. Used to provide information about the API (licensing, contact, ...)
+- `ChannelV2`: Marks a method or class for code-first `AsyncAPI` channel generation. Used to provide information about the channel marked methods belong to.
+- `OperationV2`: Marks a method for code-first `AsyncAPI` operation generation. Use to provide information about the `AsyncAPI` operation.
+
+#### AsyncAPI V3
+
+```csharp
+
+```
 
 #### 2.1. Generating documents manually
 
 ```csharp
 var generator = serviceProvider.GetRequiredService<IAsyncApiDocumentGenerator>();
 var options = new AsyncApiDocumentGenerationOptions()
 {
-    DefaultConfiguration = builder =>
+    DefaultV2Configuration = builder =>
+    {
+        //Setup V2 documents, by configuring servers, for example
+    };
+    DefaultV3Configuration = builder =>
     {
-        //Setup the document by configuring servers, for example
+        //Setup V3 documents, by configuring servers, for example
     }
 };
 IEnumerable<AsyncApiDocument> documents = generator.GenerateAsync(typeof(StreetLightsService), options);
@@ -239,9 +260,10 @@ public class Startup
         //Registers and configures the AsyncAPI code-first generation
         services.AddAsyncApiGeneration(builder => 
             builder.WithMarkupType<StreetLightsService>()
-                .UseDefaultConfiguration(asyncApi =>
+                .UseDefaultV2Configuration(asyncApi =>
                 {
-                    asyncApi.UseServer("mosquitto", server => server
+                    asyncApi
+                        .UseServer("mosquitto", server => server
                         .WithUrl(new Uri("mqtt://test.mosquitto.org"))
                         .WithProtocol(AsyncApiProtocols.Mqtt));
                 }));
@@ -284,12 +306,12 @@ Launch your ASP project, then navigate to `http://localhost:44236/asyncapi`. You
 
 ### [Streetlights API - Server](https://github.com/neuroglia-io/AsyncApi/tree/main/samples/StreetLightsApi/Server)
 
-A simple `ASP.NET 5.0` REST API using a MQTT-powered message bus to send and receive information about environmental lighting conditions for a particular streetlight.
+A simple `ASP.NET 9.0` REST API using a MQTT-powered message bus to send and receive information about environmental lighting conditions for a particular streetlight.
 
 Clone the project in your favorite IDE, launch the app, and navigate to `https://localhost:44326/asyncapi/StreetLightsApi/1.0.0`. You should see something like the following:
 
 ```yaml
-asyncapi: 2.1.0
+asyncapi: 2.6.0
 info:
   title: Streetlights API
   version: 1.0.0

src/Neuroglia.AsyncApi.AspNetCore.UI/Models/AsyncApiDocumentViewModel.cs → samples/StreetLightsApi/Messages/AddStreetLightRequest.cs

@@ -11,23 +11,27 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-namespace Neuroglia.AsyncApi.AspNetCore.UI.Models;
+namespace StreetLightsApi.Messages;
 
 /// <summary>
-/// Holds the data used to render an <see cref="AsyncApiDocument"/> view
+/// Represents a request to add a new street light
 /// </summary>
-public record AsyncApiDocumentViewModel
+public class AddStreetLightRequest
 {
 
     /// <summary>
-    /// Initializes a new <see cref="AsyncApiDocumentViewModel"/>
+    /// Gets/sets the id of the street to add a new light to
     /// </summary>
-    /// <param name="document">The <see cref="AsyncApiDocument"/> to render the view for</param>
-    public AsyncApiDocumentViewModel(AsyncApiDocument document) => this.Document = document;
+    public required string StreetId { get; init; }
 
     /// <summary>
-    /// Gets the <see cref="AsyncApiDocument"/> to render the view for
+    /// Gets/sets the latitude of the light to add
     /// </summary>
-    public AsyncApiDocument Document { get; }
+    public required decimal Latitude { get; init; }
 
-}
+    /// <summary>
+    /// Gets/sets the longitude of the light to add
+    /// </summary>
+    public required decimal Longitude { get; init; }
+
+}

samples/StreetLightsApi/Messages/LightMeasuredEvent.cs

@@ -11,33 +11,30 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-using Json.Schema.Generation;
-using Neuroglia.AsyncApi;
+using Neuroglia.AsyncApi.v2;
 
 namespace StreetLightsApi.Server.Messages;
 
 [Tag("light", "A tag for light-related messages"), Tag("measurement", "A tag for measurement-related messages")]
 [Message(Name = "LightMeasured", Description = "A message used to measure light")]
 public class LightMeasuredEvent
 {
 
     [Required, Description("The id of the measured light ")]
     public Guid Id { get; set; }
 
     [Required, Description("The type of the measured light")]
     public StreetLightType Type { get; set; }
 
     [Required, Description("The specified light's lumens measurement")]
     public int Lumens { get; set; }
 
     [Required, Description("The date and time at which the event has been created")]
     public DateTime SentAt { get; set; }
 
     [Description("The event's metadata")]
     public IDictionary<string, string>? Metadata { get; set; }
 
-    public List<Todo> Todos { get; set; }
+    public List<TodoItem> Todo { get; set; } = [];
 
 }
-
-public record Todo(string Name);

src/Neuroglia.AsyncApi.Core/v2/Bindings/Sns/SnsMessageBindingDefinition.cs → samples/StreetLightsApi/Messages/MeasureStreetLightLuminosityReply.cs

@@ -11,15 +11,17 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-namespace Neuroglia.AsyncApi.v2.Bindings.Sns;
+namespace StreetLightsApi.Messages;
 
 /// <summary>
-/// Represents the object used to configure a SNS message binding
+/// Represents the response to a measure street light luminosity request
 /// </summary>
-[DataContract]
-public record SnsMessageBindingDefinition
-    : SnsBindingDefinition, IMessageBindingDefinition
+public class MeasureStreetLightLuminosityReply
 {
 
+    /// <summary>
+    /// Gets/sets the street light's lumens
+    /// </summary>
+    public required long Lumens { get; init; }
 
 }

samples/StreetLightsApi/Messages/MovementDetectedEvent.cs

@@ -11,22 +11,19 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-using Neuroglia.AsyncApi;
-using System.ComponentModel;
+using Neuroglia.AsyncApi.v2;
 
-namespace StreetLightsApi.Server.Messages
-{
-    [Tag("movement", "A tag for movement-related messages"), Tag("sensor", "A tag for sensor-related messages")]
-    [Message(Name = "MovementDetected")]
-    public class MovementDetectedEvent
-    {
+namespace StreetLightsApi.Server.Messages;
 
-        [Description("The id of the sensor that has detected movement")]
-        public int SensorId { get; set; }
+[Tag("movement", "A tag for movement-related messages"), Tag("sensor", "A tag for sensor-related messages")]
+[Message(Name = "MovementDetected")]
+public class MovementDetectedEvent
+{
 
-        [Description("The date and time at which the event has been created")]
-        public DateTime SentAt { get; set; }
+    [Description("The id of the sensor that has detected movement")]
+    public int SensorId { get; set; }
 
-    }
+    [Description("The date and time at which the event has been created")]
+    public DateTime SentAt { get; set; }
 
 }