Softata: An ASP.NET Core API Interface - 2
About setting up an ASP.NET Core API app enhanced with XML comments as with the SoftataWebApp app.
Try the Softata Swagger on Azure:
Link: softatawebapi on azurewebsites.net Nb Link here may change.
Will separately need the Pico up and running to action API but can c=view it here without.
Nb: Is minus MetaInfo as below … working on it.
Links
- Get started with Swashbuckle and ASP.NET Core: MS Learn/.NET/ASP.NET Core
- Implement API Documentation in .NET 7: Swagger, OpenAPI, and XML Comments: A post by Egwuda Ujenyuojo:
Softata Links
- The GitHub Repository: djaus2/Soft-ata
- Blog posts index: Softata
About
The previous post provided an overview of the ASP.NET Core API app for the SoftataLib C# library. This library invokes individual Softata methods on a RPi Pico W running as an Arduino device. Invocation is via a TCPIP service running on the Pico. The methods interact with various devices connected to the Pico.
Softata enables the remote interaction with Arduino peripherals by a .NET app whether a Console, Blazor and now ASP.NET app.
This post look at the ASP.NET Core aspects of the SoftataWebAPI app.
Overview
The task was to create an ASP.NET Core app that wrappers the SoftataLib methods as ASP.NET Controller methods. The main classes in SoftataLib are:
- SoftaLib (The main class)
- Connectivity
- low level calls to the server, etc.
- Sensors
- Setup
- Read
- Displays
- Setup
- Write
- Actuators
- Setup
- Write
SoftatWebAPI mirrors each of those as a controller.
Setup
In Visual Studio (Version 17.9.3) a new project was created using the “ASP.NET Core Web API” template, making sure the following where enabled on the second dialog:
- Enable OpenAI Support
- Use Controllers
This is discussed in more detail in links 1 and 2 above.
When this is built and run you get the Swagger interface to the /WeatherForecast [Get] method.
Get Post Put Delete
The web terms Get Post Put and Delete are verbs that refer specifically to Database functions. By how do they map onto more general functionality in an ASP.NET Controller.
- Get: Get information
- Post: Post a new entity
- Put : Update an existing entity
- Delete: Delete an entity
The Softata has various methods with various types of functions. Some are clearly a Get Operation:
- GetDeviceTypes
- GetSensors
- GetPins
- ReadSensor
What about Setup for a specific device? This context has been interpreted as a Post returning Ok or Fail. With Ok, an index for the the instantiation is returned which is used to identify the device in subsequent calls
Is writing a value to a display or actuator a Post or Put? Philosophically, it is probably a Put as it is modifying an existing (instantiated) device. Post was though used also returning Ok or Fail. Disconnecting a device is probably a Delete but that disconnection is not supported by Softata.
The SensorController Interface:
namespace SoftataWebAPI.Controllers
{
public interface ISoftataSensorController
{
// Get methods
IEnumerable<string> Get(); //Get Sensors
string GetPins(int isensor);
IEnumerable<string> GetProperties(int isensor);
double Read(int sensorListIndex, int property);
IEnumerable<double> ReadAll(int sensorListIndex);
string ReadTelemetry(int sensorListIndex);
// Post methods
IActionResult Setup(int isensor, int pin, List<byte> settings = null);
IActionResult SetupDefault(int isensor);
}
}
ActuatorController Methods
public interface ISoftataActuatorController
{
// Get Methods
IEnumerable<string> Get(); //Get Actuators
string GetPins(int iactuator);
string GetValueRange(int iactuator);
// Post Methods
IActionResult Setup(int iactuator, int pin, List<byte> settings = null);
IActionResult SetupDefault(int iactuator);
IActionResult WriteByte(int displayLinkedListIndex, int value);
}
Link 2 provides detail guidance for using Controller method’s metadata with Swagger. For example the Summary and Parameter information that can be initiated for a method by entering ///
just above it. For example (the green comments below)
/// <summary>
/// Write a byte to Actuator
/// </summary>
/// <param name="actuatorListIndex">Display Instance index</param>
/// <param name="value">Value to set</param>
/// <returns>OK or Fail</returns>
// POST api/<SoftataController>
[Route("WriteByte")]
[HttpPost]
public IActionResult WriteByte(int actuatorListIndex, int value)
{
bool result = SoftataLib.Actuator.ActuatorWrite((byte)actuatorListIndex, (byte)value);
if (!result)
{
return BadRequest("Actuator:WriteByte fail.");
}
return Ok($"Actuator:WriteByte");
}
When the steps outlined in Link 2 above, these then appear in the Swagger UI for a method:
Before metainfo is added
After metainfo is added
As per Link 1, even more details can be made available in Swagger with more metainfo embedded in the code.
Footnote
In deploying to Azure you get an error A call to warmup your site failed with response code: ‘InternalServerError’. This was “fixed” by commenting out c.IncludeXmlComments(xmlPath);
in Program.cs but means the meta-info doesn’t get generated/displayed.
Also, ultimately the //if (app.Environment.IsDevelopment())
condition needs to be removed (leaving the two UseSwagger actions always operable).
Conclusion
Swagger provides a useful test environment for ASP.NET Web APIs and can be significantly enhanced by adding meta-information about controller methods as XML Document Comments: Comments immediately above a method.
Topic | Subtopic | |
This Category Links | ||
Category: | Softata Index: | Softata |
Next: > | Softata | Many ways to skin a cat |
< Prev: | Softata | An ASP.NET Core API Interface - 1 |