Displaying enum values together with a referenced class in Swagger using Swashbuckle

Question

I am using Swashbuckle to generate Swagger output. On my model I the following property:

public FieldValue? MyProperty { get; set; }

FieldValue is a simple class that can hold an ID and a name:

public class FieldValue
{
    /// <summary>
    /// The numerical represenation of the value.
    /// </summary>
    /// <example>1</example>
    public string Id { get; set; }

    /// <summary>
    /// The textual represenation of the value.
    /// </summary>
    /// <example>SomeValue</example>
    public string Name { get; set; }
}

Via some business logic in our code, a set of possible key-value pairs (ID and name) are mapped to this property.

Now, I would like to show all the possible values for MyProperty in the enum tag in my Swagger output. Using an implementation of ISchemaFilter, a custom attribute on the MyProperty property and using allOf instead of a simple ref, I have managed to add the values in my JSON output, see below. The reason for using allOf instead of just ref is that ref will overwrite all properties on the referencing schema. So, when I use allOf it keeps my description and enum fields in the document.

{
    "components": {
        "schemas": {
            "FieldValue": {
                "type": "object",
                "properties": {
                    "Id": {
                        "type": "string",
                        "description": "The numerical represenation of the value.",
                        "nullable": true,
                    },
                    "Name": {
                        "type": "string",
                        "description": "The textual represenation of the value.",
                        "nullable": true,
                    }
                }
            },
            "MyProperty": {
                "enum": [
                    "1: EnumValue1",
                    "2: EnumValue2",
                    "3: EnumValue3"
                ],
                "allOf": [{
                        "$ref": "#/components/schemas/FieldValue"
                    }
                ],
                "description": "Some description",
                "nullable": true
            }
    }
}

This does not show the enum-values in the Swagger UI, though. It does show the description.

Is this Swagger doc valid? If not, how can I make it valid and display the enums for MyProperty?

Answer 1

The correct representation of your use case is:

  "MyProperty": {
    "enum": [
      {"Id": "1", "Name": "EnumValue1"},
      {"Id": "2", "Name": "EnumValue2"},
      {"Id": "3", "Name": "EnumValue3"}
    ],
    "allOf": [
       { "$ref": "#/components/schemas/FieldValue" }
     ],
    "description": "Some description",
    "nullable": true
  }

However, there's little to no tooling support for enums containing object literals. I suggest mentioning the possible Id and Name values in the description of the MyProperty property.