Softata: Open AI and Enums with Blockly & Swagger Part 1


With Blockly and Swagger, where a Controller Method/Setup Block needs to define the Actuator/Display/Sensor, you need to enter an ordinal for the device type. Because that is an integer parameter, any value, valid or not can be entered. Firstly, how do you restrict it to valid enum ordinals for the device type? Secondly, as that manifests as a dropdown list of valid ordinals, how can the dropdown list be the enum literals. Further, how can that be applied for any Controller Method that can use enum types as parameters, manifesting as dropdown lists in Blockly Blocks and Swagger Methods?

OpenAPI

“The OpenAPI Specifications provides a formal standard for describing HTTP APIs. This allows people to understand how an API works, how a sequence of APIs work together, generate client code, create tests, apply design standards, and much, much more.” Ref OpenAI.org

Earlier, Web Services provided web APIs based upon SOAP and WSDL. Using Web services, you can exchange loosely coupled data as XML messages between heterogeneous systems.

Through OpenAPI Swagger as “a simple contract for an API.” The idea is to keep it simple enough that people would actually use it.

NetCoreBlockly, as used by Softata, builds upon Swagger to provide programming blocks coded as ASP.NET Controllers.

The Issue Part 1

This issue was posted on the NetCoreBlockly site: Given an enum type as parameter to a Controller, can the enum literals show rather than the ordinal? #172

I have a setup controller that takes an index idisplay which determines the display to be setup:

[Route("SetupDefault")]
[HttpPost] // Default setup for display
public IActionResult SetupDefault(int idisplay=0)
{
    ...
}

The displays are defined as an enum:

public enum DisplayDevice : byte { OLED096, LCD1602, NEOPIXEL,BARGRAPH,GBARGRAPH }

So you enter the ordinal {0 … 4} in the blue number attached to the block to determine the display type used.

Wouldn’t it be “nicer” if there was a list of display types as a dropdown menu there.** Read on …

The Issue Part 2

So if I add a controller SetupDefaultfromList thus:

[Route("SetupDefaultfromList")]
[HttpPost] // Default setup for display from list
public IActionResult SetupDefaultfromList(DisplayDevice idisplay )
{
    ...
}

If you select the Display/SetupDefaultfromList block you now get the the block as above. But because the DisplayDevice type has been used as a parameter type to the Controller method, you now get DeviceType as an object that can be used (In Blockly: Swagger/MySite/API/Objects):

This can then be affixed to the block thus:

But the selection menu only allows selection of a valid {0..4} ordinal for the DisplayDevice type. This does work, but you need to externally know the ordinals for each display. In Swagger it tells you what ordinals are valid and when the activated, they are are the dropdown menu {0 … 4} also.

Again, would it be “nice” to have teh display device names as the selectable values?

The Solution

The solution was supplied by the NetCoreBlockly author Andrei Ignat. Add the following in Progracs/

    builder.Services.AddControllers().AddJsonOptions(
        options =>options.JsonSerializerOptions.Converters.Add(
            new JsonStringEnumConverter()));

And now the DisplayType block is a menu of display type literals:

And now the setup is quite explicit wrt the device type:

**Next: ** Part 2: Other enums as Blockly parameters

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