Merge branch 'develop'

Core/SmartIOT.Connector.Core/SmartIOT.Connector.Core.csproj

@@ -6,7 +6,7 @@
     <Nullable>enable</Nullable>
 	<Authors>Luca Domenichini</Authors>
 	<Title>SmartIOT.Connector Core Library</Title>
-	<Description>The SmartIOT.Connector Core library provides you with a scheduler runnable on the cloud that is able to publish to an external service the events captured from IoT devices or industrial PLCs</Description>
+	<Description>The SmartIOT.Connector Core library provides you a scheduler runnable on the cloud that is able to publish to an external service the events captured from IoT devices or industrial PLCs</Description>
 	<PackageProjectUrl>https://github.com/luca-domenichini/SmartIOT.Connector</PackageProjectUrl>
 	<RepositoryUrl>https://github.com/luca-domenichini/SmartIOT.Connector.git</RepositoryUrl>
 	<RepositoryType>git</RepositoryType>

Core/SmartIOT.Connector.RestApi/Controllers/V1/ConfigurationController.cs

@@ -3,6 +3,7 @@
 using Microsoft.AspNetCore.Mvc;
 using SmartIOT.Connector.Core;
 using SmartIOT.Connector.RestApi.Services;
+using Swashbuckle.AspNetCore.Annotations;
 
 namespace SmartIOT.Connector.RestApi.Controllers.V1;
 
@@ -27,6 +28,7 @@ public ConfigurationController(IConfigurationService configurationService)
     [HttpGet]
     [MapToApiVersion("1.0")]
     [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(SmartIotConnectorConfiguration))]
+    [SwaggerOperation("This method returns the current configuration")]
     public SmartIotConnectorConfiguration GetConfiguration()
     {
         return _configurationService.GetConfiguration();
@@ -38,6 +40,7 @@ public SmartIotConnectorConfiguration GetConfiguration()
     [HttpPut]
     [MapToApiVersion("1.0")]
     [ProducesResponseType(StatusCodes.Status200OK)]
+    [SwaggerOperation("This method persists the configuration on disk")]
     public IActionResult SaveConfiguration()
     {
         _configurationService.SaveConfiguration();

Core/SmartIOT.Connector.RestApi/Controllers/V1/ConnectorController.cs

@@ -3,6 +3,7 @@
 using Microsoft.AspNetCore.Mvc;
 using SmartIOT.Connector.Core;
 using SmartIOT.Connector.RestApi.Services;
+using Swashbuckle.AspNetCore.Annotations;
 
 namespace SmartIOT.Connector.RestApi.Controllers.V1;
 
@@ -32,6 +33,7 @@ public ConnectorController(SmartIotConnector smartIotConnector, IConnectorServic
     [HttpGet]
     [MapToApiVersion("1.0")]
     [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(List<Model.Connector>))]
+    [SwaggerOperation("Returns the list of Connectors currently managed by SmartIOT.Connector")]
     public IList<Model.Connector> GetConnectors()
     {
         return _smartIotConnector.Connectors.Select((x, i) => new Model.Connector(i, x.ConnectionString)).ToList();
@@ -46,6 +48,7 @@ public ConnectorController(SmartIotConnector smartIotConnector, IConnectorServic
     [Route("{index}")]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
     [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(Model.Connector))]
+    [SwaggerOperation("Gets the zero based Connector as defined in the configuration or 404 not found")]
     public IActionResult GetConnector(int index)
     {
         var list = _smartIotConnector.Connectors;
@@ -67,7 +70,9 @@ public IActionResult GetConnector(int index)
     [Route("{index}")]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
     [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(Model.Connector))]
-    public async Task<IActionResult> UpdateConnector(int index, [FromBody] string connectionString)
+    [SwaggerOperation("Updates an existing Connector and completely replace it with the new one passed in the connectionString.")]
+    public async Task<IActionResult> UpdateConnector([SwaggerParameter("The zero based index of the Connector")] int index
+        , [SwaggerParameter("The connectionString that defines the Connector")][FromBody] string connectionString)
     {
         if (await _connectorsService.ReplaceConnectorAsync(index, connectionString))
             return Ok(new Model.Connector(index, connectionString));
@@ -82,6 +87,7 @@ public async Task<IActionResult> UpdateConnector(int index, [FromBody] string co
     [HttpPost]
     [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(Model.Connector))]
     [ProducesResponseType(StatusCodes.Status400BadRequest)]
+    [SwaggerOperation("Creates a new Connector as defined in the connectionString.")]
     public async Task<IActionResult> AddConnector([FromBody] string connectionString)
     {
         var connector = await _connectorsService.AddConnectorAsync(connectionString);
@@ -99,6 +105,7 @@ public async Task<IActionResult> AddConnector([FromBody] string connectionString
     [Route("{index}")]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
     [ProducesResponseType(StatusCodes.Status200OK)]
+    [SwaggerOperation("Deletes an already defined Connector. Be aware that deleting a Connector, may rescale other Connector indexes as well. Deleting the index 0, makes all Connectors scale their index by -1.")]
     public async Task<IActionResult> RemoveConnector(int index)
     {
         if (await _smartIotConnector.RemoveConnectorAsync(index))

Core/SmartIOT.Connector.RestApi/Controllers/V1/DeviceController.cs

@@ -5,6 +5,7 @@
 using SmartIOT.Connector.Core.Conf;
 using SmartIOT.Connector.RestApi.Model;
 using SmartIOT.Connector.RestApi.Services;
+using Swashbuckle.AspNetCore.Annotations;
 
 namespace SmartIOT.Connector.RestApi.Controllers.V1;
 
@@ -31,6 +32,7 @@ public DeviceController(SmartIotConnector smartIotConnector, IDeviceService devi
     [MapToApiVersion("1.0")]
     [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(List<DeviceConfiguration>))]
     [Route("configuration")]
+    [SwaggerOperation("Returns the devices configuration")]
     public IActionResult GetConfiguration()
     {
         return Ok(_deviceService.GetDeviceConfigurations());
@@ -45,7 +47,8 @@ public IActionResult GetConfiguration()
     [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(DeviceConfiguration))]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
     [Route("configuration/{deviceId}")]
-    public IActionResult GetDeviceConfiguration(string deviceId)
+    [SwaggerOperation("Returns the requested device configuration, or 404 if not found")]
+    public IActionResult GetDeviceConfiguration([SwaggerParameter("The deviceId to use")] string deviceId)
     {
         var device = _deviceService.GetDeviceConfiguration(deviceId);
         if (device != null)
@@ -63,7 +66,8 @@ public IActionResult GetDeviceConfiguration(string deviceId)
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status400BadRequest)]
     [Route("configuration")]
-    public async Task<IActionResult> AddDevice([FromBody] DeviceConfiguration deviceConfiguration)
+    [SwaggerOperation("Adds a new device, or 400 if device already exists")]
+    public async Task<IActionResult> AddDevice([SwaggerParameter("The device configuration to add to the scheduler")][FromBody] DeviceConfiguration deviceConfiguration)
     {
         try
         {
@@ -85,7 +89,8 @@ public async Task<IActionResult> AddDevice([FromBody] DeviceConfiguration device
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status400BadRequest)]
     [Route("configuration/{deviceId}")]
-    public async Task<IActionResult> RemoveDevice(string deviceId)
+    [SwaggerOperation("Removes an existing device, or 400 if device already exists")]
+    public async Task<IActionResult> RemoveDevice([SwaggerParameter("The deviceId to use")] string deviceId)
     {
         try
         {
@@ -107,7 +112,8 @@ public async Task<IActionResult> RemoveDevice(string deviceId)
     [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(bool))]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
     [Route("configuration/{deviceId}/enabled")]
-    public IActionResult IsDeviceEnabled(string deviceId)
+    [SwaggerOperation("Returns true if the device is enabled, or 404 if not found")]
+    public IActionResult IsDeviceEnabled([SwaggerParameter("The deviceId to use")] string deviceId)
     {
         var device = _smartIotConnector.Schedulers
             .Select(x => x.Device)
@@ -129,7 +135,9 @@ public IActionResult IsDeviceEnabled(string deviceId)
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
     [Route("configuration/{deviceId}/enabled")]
-    public IActionResult SetDeviceEnabled(string deviceId, [FromBody] bool enabled)
+    [SwaggerOperation("Enables or disables a device. Returns 404 if not found")]
+    public IActionResult SetDeviceEnabled([SwaggerParameter("The deviceId to use")] string deviceId
+        , [SwaggerParameter("true or false to enable the device")][FromBody] bool enabled)
     {
         var device = _smartIotConnector.Schedulers
             .Select(x => x.Device)
@@ -153,7 +161,9 @@ public IActionResult SetDeviceEnabled(string deviceId, [FromBody] bool enabled)
     [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(TagConfiguration))]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
     [Route("configuration/{deviceId}/tags/{tagId}")]
-    public IActionResult GetTagConfiguration(string deviceId, string tagId)
+    [SwaggerOperation("Returns the requested tag configuration, or 404 if not found")]
+    public IActionResult GetTagConfiguration([SwaggerParameter("The deviceId to use")] string deviceId
+        , [SwaggerParameter("The tagId to use")] string tagId)
     {
         var tag = _deviceService.GetTagConfiguration(deviceId, tagId);
         if (tag != null)
@@ -172,7 +182,9 @@ public IActionResult GetTagConfiguration(string deviceId, string tagId)
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status400BadRequest)]
     [Route("configuration/{deviceId}/tags")]
-    public IActionResult AddTag(string deviceId, [FromBody] TagConfiguration tagConfiguration)
+    [SwaggerOperation("Adds a new tag, or 400 something wrong with the request")]
+    public IActionResult AddTag([SwaggerParameter("The deviceId to use")] string deviceId
+        , [SwaggerParameter("The Tag configuration to add")][FromBody] TagConfiguration tagConfiguration)
     {
         try
         {
@@ -195,7 +207,9 @@ public IActionResult AddTag(string deviceId, [FromBody] TagConfiguration tagConf
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status400BadRequest)]
     [Route("configuration/{deviceId}/tags/{tagId}")]
-    public IActionResult RemoveTag(string deviceId, string tagId)
+    [SwaggerOperation("Removes an existing tag, or 400 something wrong with the request")]
+    public IActionResult RemoveTag([SwaggerParameter("The deviceId to use")] string deviceId
+        , [SwaggerParameter("The tagId to use")] string tagId)
     {
         try
         {
@@ -218,7 +232,9 @@ public IActionResult RemoveTag(string deviceId, string tagId)
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status400BadRequest)]
     [Route("configuration/{deviceId}/tags")]
-    public IActionResult UpdateTag(string deviceId, [FromBody] TagConfiguration tagConfiguration)
+    [SwaggerOperation("Updates an existing tag, or 400 something wrong with the request")]
+    public IActionResult UpdateTag([SwaggerParameter("The deviceId to use")] string deviceId
+        , [SwaggerParameter("The updated configuration for the tag")][FromBody] TagConfiguration tagConfiguration)
     {
         try
         {
@@ -245,7 +261,9 @@ public IActionResult UpdateTag(string deviceId, [FromBody] TagConfiguration tagC
     [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(TagData))]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
     [Route("data/{deviceId}/{tagId}")]
-    public IActionResult GetTagData(string deviceId, string tagId)
+    [SwaggerOperation("Returns the requested data, or 404 if not found")]
+    public IActionResult GetTagData([SwaggerParameter("The deviceId to use")] string deviceId
+        , [SwaggerParameter("The tagId to use")] string tagId)
     {
         var data = _deviceService.GetTagData(deviceId, tagId);
         if (data != null)
@@ -265,7 +283,10 @@ public IActionResult GetTagData(string deviceId, string tagId)
     [ProducesResponseType(StatusCodes.Status200OK)]
     [ProducesResponseType(StatusCodes.Status400BadRequest)]
     [Route("data/{deviceId}/{tagId}")]
-    public IActionResult SetTagData(string deviceId, string tagId, [FromBody] TagData tagData)
+    [SwaggerOperation("Updates the requested data, or 400 something wrong with the request")]
+    public IActionResult SetTagData([SwaggerParameter("The deviceId to use")] string deviceId
+        , [SwaggerParameter("The tagId to use")] string tagId
+        , [SwaggerParameter("The data to insert in the tag")][FromBody] TagData tagData)
     {
         try
         {
@@ -289,6 +310,7 @@ public IActionResult SetTagData(string deviceId, string tagId, [FromBody] TagDat
     [MapToApiVersion("1.0")]
     [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(List<Device>))]
     [Route("status")]
+    [SwaggerOperation("Returns the list of configured devices")]
     public IActionResult GetDevices()
     {
         return Ok(_deviceService.GetDevices());
@@ -303,7 +325,8 @@ public IActionResult GetDevices()
     [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(Device))]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
     [Route("status/{deviceId}")]
-    public IActionResult GetDevice(string deviceId)
+    [SwaggerOperation("Returns the requested device, or 404 if not found")]
+    public IActionResult GetDevice([SwaggerParameter("The deviceId to use")] string deviceId)
     {
         var device = _deviceService.GetDevice(deviceId);
         if (device != null)
@@ -322,7 +345,9 @@ public IActionResult GetDevice(string deviceId)
     [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(Tag))]
     [ProducesResponseType(StatusCodes.Status404NotFound)]
     [Route("status/{deviceId}/{tagId}")]
-    public IActionResult GetTag(string deviceId, string tagId)
+    [SwaggerOperation("Returns the requested tag, or 404 if not found")]
+    public IActionResult GetTag([SwaggerParameter("The deviceId to use")] string deviceId
+        , [SwaggerParameter("The tagId to use")] string tagId)
     {
         var tag = _deviceService.GetTag(deviceId, tagId);
         if (tag != null)

Core/SmartIOT.Connector.RestApi/Controllers/V1/SchedulerController.cs

@@ -3,6 +3,7 @@
 using Microsoft.AspNetCore.Mvc;
 using SmartIOT.Connector.Core;
 using SmartIOT.Connector.Core.Conf;
+using Swashbuckle.AspNetCore.Annotations;
 
 namespace SmartIOT.Connector.RestApi.Controllers.V1;
 
@@ -27,6 +28,7 @@ public SchedulerController(SmartIotConnector smartIotConnector)
     [HttpGet]
     [MapToApiVersion("1.0")]
     [ProducesResponseType(StatusCodes.Status200OK, Type = typeof(SchedulerConfiguration))]
+    [SwaggerOperation("This method returns the current configuration")]
     public SchedulerConfiguration GetConfiguration()
     {
         return _smartIotConnector.SchedulerConfiguration;
@@ -38,6 +40,7 @@ public SchedulerConfiguration GetConfiguration()
     [HttpPut]
     [MapToApiVersion("1.0")]
     [ProducesResponseType(StatusCodes.Status200OK)]
+    [SwaggerOperation("This method changes the current scheduler configuration")]
     public IActionResult SetConfiguration([FromBody] SchedulerConfiguration configuration)
     {
         configuration.CopyTo(_smartIotConnector.SchedulerConfiguration);

Core/SmartIOT.Connector.RestApi/Model/Connector.cs

@@ -1,15 +1,19 @@
-namespace SmartIOT.Connector.RestApi.Model;
+using Swashbuckle.AspNetCore.Annotations;
+
+namespace SmartIOT.Connector.RestApi.Model;
 
 public class Connector
 {
     /// <summary>
     /// Index of the connector in SmartIOT.Connector list
     /// </summary>
+    [SwaggerSchema("Index of the connector in SmartIOT.Connector list", Nullable = false)]
     public int Index { get; }
 
     /// <summary>
     /// ConnectionString with connector parameters
     /// </summary>
+    [SwaggerSchema("ConnectionString with connector parameters", Nullable = false)]
     public string ConnectionString { get; }
 
     public Connector(int index, string connectionString)

Core/SmartIOT.Connector.RestApi/Model/Device.cs

@@ -1,4 +1,5 @@
 using SmartIOT.Connector.Core.Model;
+using Swashbuckle.AspNetCore.Annotations;
 
 namespace SmartIOT.Connector.RestApi.Model;
 
@@ -7,16 +8,19 @@ public class Device
     /// <summary>
     /// The device Id
     /// </summary>
+    [SwaggerSchema("The device Id", Nullable = false)]
     public string DeviceId { get; }
 
     /// <summary>
     /// The device status
     /// </summary>
+    [SwaggerSchema("The device status", Nullable = false)]
     public DeviceStatus DeviceStatus { get; }
 
     /// <summary>
     /// The list of tags managed by this device
     /// </summary>
+    [SwaggerSchema("The list of tags managed by this device", Nullable = false)]
     public IList<Tag> Tags { get; }
 
     public Device(string deviceId, DeviceStatus deviceStatus, IList<Tag> tags)

Core/SmartIOT.Connector.RestApi/Model/Scheduler.cs

@@ -1,4 +1,5 @@
 using SmartIOT.Connector.Core.Conf;
+using Swashbuckle.AspNetCore.Annotations;
 
 namespace SmartIOT.Connector.RestApi.Model;
 
@@ -7,21 +8,25 @@ public class Scheduler
     /// <summary>
     /// Scheduler index
     /// </summary>
+    [SwaggerSchema("Scheduler index", Nullable = false)]
     public int Index { get; }
 
     /// <summary>
     /// Scheduler name describing the devices
     /// </summary>
+    [SwaggerSchema("Scheduler name describing the devices", Nullable = false)]
     public string Name { get; }
 
     /// <summary>
     /// Scheduler status
     /// </summary>
+    [SwaggerSchema("Scheduler status", Nullable = false)]
     public bool Active { get; }
 
     /// <summary>
     /// The device attached to current scheduler
     /// </summary>
+    [SwaggerSchema("The device attached to current scheduler", Nullable = false)]
     public DeviceConfiguration Device { get; }
 
     public Scheduler(int index, string name, bool active, DeviceConfiguration device)

Core/SmartIOT.Connector.RestApi/SmartIOT.Connector.RestApi.csproj

@@ -4,10 +4,9 @@
     <TargetFrameworks>net8.0</TargetFrameworks>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-	<GenerateDocumentationFile>true</GenerateDocumentationFile>
 	<Authors>Luca Domenichini</Authors>
 	<Title>SmartIOT.Connector REST API Library</Title>
-	<Description>The SmartIOT.Connector REST API library provides you with the REST controllers needed to interact with SmartIOT.Connector with RESTful services</Description>
+	<Description>The SmartIOT.Connector REST API library provides you the REST controllers needed to interact with SmartIOT.Connector with RESTful services</Description>
 	<PackageProjectUrl>https://github.com/luca-domenichini/SmartIOT.Connector</PackageProjectUrl>
 	<RepositoryUrl>https://github.com/luca-domenichini/SmartIOT.Connector.git</RepositoryUrl>
 	<RepositoryType>git</RepositoryType>

Core/SmartIOT.Connector.RestApi/SwaggerVersioningOptions.cs

@@ -17,13 +17,12 @@ public SwaggerVersioningOptions(IApiVersionDescriptionProvider provider)
 
     public void Configure(SwaggerGenOptions options)
     {
+        options.EnableAnnotations();
+
         // add swagger document for every API version discovered
         foreach (var description in provider.ApiVersionDescriptions)
         {
             options.SwaggerDoc(description.GroupName, CreateVersionInfo(description));
-
-            var filePath = Path.Combine(System.AppContext.BaseDirectory, "SmartIOT.Connector.RestApi.xml");
-            options.IncludeXmlComments(filePath);
         }
     }