0

I'm building a REST API and a lot of the objects it returns are designed with a number of Enums for various settings.

Having read up on it, and in particular using advice from this SO Question:

Swagger UI Web Api documentation Present enums as strings?

I have set up my Global.asax to enable Swagger with the DescribeAllEnumsAsStrings option:

enter image description here

(It should be noted here that the parent project which provides the API is a .NET Framework application, written in VB which I do plan to convert to a .NET Core application but being a big project, migration will take time, so code above is for .NET Framework VB, whereas code below, the consuming Client is a .NET Core website application using C#)

The client code (adding using Visual Studio > Add Rest Client (Swagger)) generates all the objects correctly, and Intellisense knows the string options for the Enums:

enter image description here

Yet, when I dump the JSON object fetched by the API, the Enum properties have integer values represented as strings:

enter image description here

In this instance, the API is returning some image data; images have 4 size variants and the Image.Size class gives the user information about the sizes. SizeType is an Enum used to determine which image to use for different purposes.

For the convenience of the clients using this API I would like the Enum type to be reflected and produced by the generated API code, or at least, the Enum properties be string values that correspond to the Enum name, thus a bit of code like:

i.Sizes.FirstOrDefault(s => s.SizeType.Equals("Thumb"))

or

i.Sizes.FirstOrDefault(s => s.SizeType = SizeType.Thumb)

Will be more intuitive for the user. Currently, neither of the above find the Thumbnail image size that it should, the code to fetch this Thumbnail needs to be:

i.Sizes.FirstOrDefault(s => s.SizeType = "3")

Obviously that isn't as intuitive as the above examples, and I am not sure why, or what, if any, Swagger option would change it.

Jamie Hartnoll
  • 7,231
  • 13
  • 58
  • 97
  • Yes, I realise `Enums` are just a named integer, but the whole point of naming them is for simpler, more intuitive coding, which I would like to be reflected by the generated API code. When `DescribeAllEnumsAsStrings` is set the Swagger documentation adds the names to the `Enum` and makes the property values strings, this makes it partially easier for the coding in the client app, but is not fully reflected named Enum. – Jamie Hartnoll Jul 24 '20 at 10:51
  • "4 size variants" yet you list 7 "possible values" which is it? – Mark Schultheiss Jul 24 '20 at 10:56
  • https://swagger.io/docs/specification/data-models/enums/ might help you with the value vs description of the enums for the OData/swagger schema – Mark Schultheiss Jul 24 '20 at 11:04
  • This is related but I am not 100% sure it answers your question https://stackoverflow.com/q/36452468/125981 – Mark Schultheiss Jul 24 '20 at 11:09
  • Keep in mind one of the important values of an Enum is the compile time checking. – Mark Schultheiss Jul 24 '20 at 11:15
  • Thanks for the comments and links, but none quite answer it. The related question you post is the same one I referenced in my original question, that did help and got me as far as I have got. It presents the ENUM values as strings to the user for the purpose of making requests to the API, which helps but it doesn’t make the REST client code generate the ENUM types as I’d prefer for client use. It surprises me since it generates all classes and properties, why not ENUMs? Interesting article on “why ENUMs”: https://www.thoughtco.com/what-is-an-enum-958326 – Jamie Hartnoll Jul 24 '20 at 19:14

0 Answers0