From bf892a6e861ab60d33d3bf4cd17a374bfec1416f Mon Sep 17 00:00:00 2001 From: Luca Domenichini Date: Wed, 10 Jan 2024 12:05:02 +0100 Subject: [PATCH] CHG removed generated xml doc file for API. Using swagger attributes instead. --- .../SmartIOT.Connector.Core.csproj | 2 +- .../Controllers/V1/ConfigurationController.cs | 3 ++ .../Controllers/V1/ConnectorController.cs | 9 +++- .../Controllers/V1/DeviceController.cs | 51 ++++++++++++++----- .../Controllers/V1/SchedulerController.cs | 3 ++ .../Model/Connector.cs | 6 ++- .../Model/Device.cs | 4 ++ .../Model/Scheduler.cs | 5 ++ .../SmartIOT.Connector.RestApi.csproj | 3 +- .../SwaggerVersioningOptions.cs | 5 +- 10 files changed, 70 insertions(+), 21 deletions(-) diff --git a/Core/SmartIOT.Connector.Core/SmartIOT.Connector.Core.csproj b/Core/SmartIOT.Connector.Core/SmartIOT.Connector.Core.csproj index 1af87fb..8dce0d2 100644 --- a/Core/SmartIOT.Connector.Core/SmartIOT.Connector.Core.csproj +++ b/Core/SmartIOT.Connector.Core/SmartIOT.Connector.Core.csproj @@ -6,7 +6,7 @@ enable Luca Domenichini SmartIOT.Connector Core Library - 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 + 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 https://github.com/luca-domenichini/SmartIOT.Connector https://github.com/luca-domenichini/SmartIOT.Connector.git git diff --git a/Core/SmartIOT.Connector.RestApi/Controllers/V1/ConfigurationController.cs b/Core/SmartIOT.Connector.RestApi/Controllers/V1/ConfigurationController.cs index 9affd6b..ccc7a17 100644 --- a/Core/SmartIOT.Connector.RestApi/Controllers/V1/ConfigurationController.cs +++ b/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(); diff --git a/Core/SmartIOT.Connector.RestApi/Controllers/V1/ConnectorController.cs b/Core/SmartIOT.Connector.RestApi/Controllers/V1/ConnectorController.cs index ea58a1b..d1cebc1 100644 --- a/Core/SmartIOT.Connector.RestApi/Controllers/V1/ConnectorController.cs +++ b/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))] + [SwaggerOperation("Returns the list of Connectors currently managed by SmartIOT.Connector")] public IList 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 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 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 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 AddConnector([FromBody] string connectionString) { var connector = await _connectorsService.AddConnectorAsync(connectionString); @@ -99,6 +105,7 @@ public async Task 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 RemoveConnector(int index) { if (await _smartIotConnector.RemoveConnectorAsync(index)) diff --git a/Core/SmartIOT.Connector.RestApi/Controllers/V1/DeviceController.cs b/Core/SmartIOT.Connector.RestApi/Controllers/V1/DeviceController.cs index 55837fd..798bf6e 100644 --- a/Core/SmartIOT.Connector.RestApi/Controllers/V1/DeviceController.cs +++ b/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))] [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 AddDevice([FromBody] DeviceConfiguration deviceConfiguration) + [SwaggerOperation("Adds a new device, or 400 if device already exists")] + public async Task AddDevice([SwaggerParameter("The device configuration to add to the scheduler")][FromBody] DeviceConfiguration deviceConfiguration) { try { @@ -85,7 +89,8 @@ public async Task AddDevice([FromBody] DeviceConfiguration device [ProducesResponseType(StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status400BadRequest)] [Route("configuration/{deviceId}")] - public async Task RemoveDevice(string deviceId) + [SwaggerOperation("Removes an existing device, or 400 if device already exists")] + public async Task RemoveDevice([SwaggerParameter("The deviceId to use")] string deviceId) { try { @@ -107,7 +112,8 @@ public async Task 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))] [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) diff --git a/Core/SmartIOT.Connector.RestApi/Controllers/V1/SchedulerController.cs b/Core/SmartIOT.Connector.RestApi/Controllers/V1/SchedulerController.cs index a984834..4b2ccf6 100644 --- a/Core/SmartIOT.Connector.RestApi/Controllers/V1/SchedulerController.cs +++ b/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); diff --git a/Core/SmartIOT.Connector.RestApi/Model/Connector.cs b/Core/SmartIOT.Connector.RestApi/Model/Connector.cs index 694a9af..2a33cba 100644 --- a/Core/SmartIOT.Connector.RestApi/Model/Connector.cs +++ b/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 { /// /// Index of the connector in SmartIOT.Connector list /// + [SwaggerSchema("Index of the connector in SmartIOT.Connector list", Nullable = false)] public int Index { get; } /// /// ConnectionString with connector parameters /// + [SwaggerSchema("ConnectionString with connector parameters", Nullable = false)] public string ConnectionString { get; } public Connector(int index, string connectionString) diff --git a/Core/SmartIOT.Connector.RestApi/Model/Device.cs b/Core/SmartIOT.Connector.RestApi/Model/Device.cs index 97c6bfe..2afede2 100644 --- a/Core/SmartIOT.Connector.RestApi/Model/Device.cs +++ b/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 /// /// The device Id /// + [SwaggerSchema("The device Id", Nullable = false)] public string DeviceId { get; } /// /// The device status /// + [SwaggerSchema("The device status", Nullable = false)] public DeviceStatus DeviceStatus { get; } /// /// The list of tags managed by this device /// + [SwaggerSchema("The list of tags managed by this device", Nullable = false)] public IList Tags { get; } public Device(string deviceId, DeviceStatus deviceStatus, IList tags) diff --git a/Core/SmartIOT.Connector.RestApi/Model/Scheduler.cs b/Core/SmartIOT.Connector.RestApi/Model/Scheduler.cs index 35e0709..799d38e 100644 --- a/Core/SmartIOT.Connector.RestApi/Model/Scheduler.cs +++ b/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 /// /// Scheduler index /// + [SwaggerSchema("Scheduler index", Nullable = false)] public int Index { get; } /// /// Scheduler name describing the devices /// + [SwaggerSchema("Scheduler name describing the devices", Nullable = false)] public string Name { get; } /// /// Scheduler status /// + [SwaggerSchema("Scheduler status", Nullable = false)] public bool Active { get; } /// /// The device attached to current scheduler /// + [SwaggerSchema("The device attached to current scheduler", Nullable = false)] public DeviceConfiguration Device { get; } public Scheduler(int index, string name, bool active, DeviceConfiguration device) diff --git a/Core/SmartIOT.Connector.RestApi/SmartIOT.Connector.RestApi.csproj b/Core/SmartIOT.Connector.RestApi/SmartIOT.Connector.RestApi.csproj index a4728c4..b916ff7 100644 --- a/Core/SmartIOT.Connector.RestApi/SmartIOT.Connector.RestApi.csproj +++ b/Core/SmartIOT.Connector.RestApi/SmartIOT.Connector.RestApi.csproj @@ -4,10 +4,9 @@ net8.0 enable enable - true Luca Domenichini SmartIOT.Connector REST API Library - The SmartIOT.Connector REST API library provides you with the REST controllers needed to interact with SmartIOT.Connector with RESTful services + The SmartIOT.Connector REST API library provides you the REST controllers needed to interact with SmartIOT.Connector with RESTful services https://github.com/luca-domenichini/SmartIOT.Connector https://github.com/luca-domenichini/SmartIOT.Connector.git git diff --git a/Core/SmartIOT.Connector.RestApi/SwaggerVersioningOptions.cs b/Core/SmartIOT.Connector.RestApi/SwaggerVersioningOptions.cs index ca19eb6..bd48566 100644 --- a/Core/SmartIOT.Connector.RestApi/SwaggerVersioningOptions.cs +++ b/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); } }