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.


  1. Get started with Swashbuckle and ASP.NET Core: MS Learn/.NET/ASP.NET Core
  2. Implement API Documentation in .NET 7: Swagger, OpenAPI, and XML Comments: A post by Egwuda Ujenyuojo:
  1. The GitHub Repository: djaus2/Soft-ata
  2. 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.


 TopicSubtopic
   
 This Category Links 
Category:Softata Index:Softata
  Next: > Softata
<  Prev:   Softata