Swagger with Title and Value

Question

I’m using Swashbuckle to generate a Swagger for my .NET assembly. I have an enum with non-sequential and negative values. Like the following

[JsonConverter(typeof(StringEnumConverter))]
public enum ShiftDayOffRule
{
    /// <summary>
    /// Shift has no day off rule.
    /// </summary>
    None = 0,       // DayOffNotRequired

    /// <summary>
    /// If shift with this rule is scheduled then next day must be a day off.
    /// </summary>
    OffAfter = 1,   // DayOffAfter <=> next is off

    /// <summary>
    /// If shift with this rule is scheduled then previous day must be a day off.
    /// </summary>
    OffBefore = -1, // DayOffBefore <=> previous is off

    /// <summary>
    /// If shift with this rule is scheduled then next day must be a work day.
    /// </summary>
    InAfter = 3     // DayInAfter <=> next cannot be off 
};

The values are getting reordered to 0, 1, 2, 3 instead of 0, 1, -1, 3.

How do I get the output json to include title and value like:

"dayoffRule": { 
   "description": "Day off rule for the shift. ScheduleData.Enums.ShiftDayOffRule", 
   "enum": [ 
      {"title": "None", "value": 0}, 
      {"title": "OffAfter", "value": 1}, 
      {"title": "InAfter", "value": 3}, 
      {"title": "OffBefore", "value": -1} 
    ], 
    "type": "string" 
 }

Reordering might be a bug in Swashbuckle. Re: specifying labels for enum values - OpenAPI Specification does not support this. Related feature requests: [#348](https://github.com/OAI/OpenAPI-Specification/issues/348), [#681](https://github.com/OAI/OpenAPI-Specification/issues/681). — Helen, Nov 08 '17 at 17:12

Helder Sepulveda · Answer 1 · 2017-11-09T13:20:33.920

1

Enable the DescribeAllEnumsAsStrings in your config.
That will change your enums to look like this:

    "parameters": [
      {
        "name": "dayOffRule",
        "in": "query",
        "required": true,
        "type": "string",
        "enum": [
          "None",
          "OffAfter",
          "OffBefore",
          "InAfter"
        ]
      }
    ],

You don't need both title and value...

Here is a live sample:
http://swashbuckletest.azurewebsites.net/swagger/ui/index?filter=Def#/Default/Default_Post

And if you absolutely need to include a mapping (title: value) you can inject it on the example using a SchemaFilter, here is the code:

    private class EnumExampleSchemaFilter : ISchemaFilter
    {
        public void Apply(Schema schema, SchemaRegistry schemaRegistry, Type type)
        {
            if (type == typeof(ShiftDayOffRule))
            {
                var example = new Dictionary<string, int>();
                foreach (var item in Enum.GetValues(typeof(ShiftDayOffRule)))
                {
                    example.Add(item.ToString(), (int)item);
                }
                schema.example = example;
            }
        }
    }

And here is how that will look on the swagger doc

    "Value": {
      "enum": [
        "None",
        "OffAfter",
        "OffBefore",
        "InAfter"
      ],
      "type": "string",
      "readOnly": true,
      "example": {
        "None": 0,
        "OffAfter": 1,
        "InAfter": 3,
        "OffBefore": -1
      }
    }

edited Nov 09 '17 at 13:20

answered Nov 09 '17 at 00:19

Helder Sepulveda

15,500
4
29
56

Where should I place the `EnumExampleSchemaFilter` class? Do I need to add a reference for `ISchemaFilter`? – Alex Nov 09 '17 at 16:45
The EnumExampleSchemaFilter goes on your config, look here: https://github.com/heldersepu/SwashbuckleTest/blob/master/Swagger_Test/App_Start/SwaggerConfig.cs#L140 – Helder Sepulveda Nov 09 '17 at 18:01
What I’m ultimately trying to do is have -1 as a valid value for the enum. This solution defaults the values back to 0, 1, 2, 3. If I remove `c.DescribeAllEnumsAsStrings();` I get a build error because the generate enum has _1 twice. Once for 1 and once for -1. – Alex Nov 09 '17 at 19:22
I don't get any errors can you be more specific? and my solution does not chance any defaults... DescribeAllEnumsAsStrings changes the enums from their numeric value to the string representation. – Helder Sepulveda Nov 09 '17 at 22:11
I input the following JSON into NSwagStudio `"dayoffRule": { "format": "int32", "description": "Day off rule for the shift. ScheduleData.Enums.ShiftDayOffRule", "enum": [ 0, 1, 3, -1 ], "type": "integer" },` And I get the following C# ` public enum ShiftDayoffRule { _0 = 0, _1 = 1, _3 = 3, _1 = -1, }` Notice the _1 duplicate item. – Alex Nov 09 '17 at 22:27
@Alex What is ***NSwagStudio*** and how is that related to Swashbuckle? _ I think we are jumping from one problem to another... – Helder Sepulveda Nov 09 '17 at 22:47
I'm trying to get the JSON in my Swagger in the format I specified so I can ultimately run it through NSwagStudio and generate a C# class with it. – Alex Nov 09 '17 at 22:55
Let us [continue this discussion in chat](http://chat.stackoverflow.com/rooms/158642/discussion-between-heldersepu-and-alex). – Helder Sepulveda Nov 09 '17 at 22:56

Swagger with Title and Value

1 Answers1