Swashbuckle.webapi: Enhancement: Include <summary> comments for enum values

[monkeycoder99]

If you call UseReferencedDefinitionsForEnums() in services.AddSwaggerGen() lambda, Xml comments are ignored for enum types.

VERSION:

Swashbuckle.AspNetCore 4.0.1

STEPS TO REPRODUCE:

1. Enable a C# web solution as normal with Swashbuckle. You may decide to use DescribeAllEnumsAsStrings() and UseReferencedDefinitionsForEnums(), it doesn't matter.
2. Run app and go to swagger URL.
3. Any classes that include properties whose type is an enum don't include documentation for the possible values, even if provided in the Xml comments.

See the sample classes below.

/// <summary>
/// My foo class
/// </summary>
public class Foo
{
    /// <summary>
    /// Describes bars
    /// </summary>
    public enum BarType
    {
        /// <summary>
        /// A special value
        /// </summary>
        SomeValue
    };

    /// <summary>
    /// Describes bars
    /// </summary>
    [JsonProperty("bar")]
    [JsonConverter(typeof(StringEnumConverter))]
    public BarType Bar { get; set; }
}

/// <summary>
/// Manages Foo.
/// </summary>
public class FooController
{
    /// <summary>
    /// Obtain a Foo.
    /// </summary>
    [HttpGet]
    public Foo Get()
    {
        return new Foo();
    }    
}

EXPECTED RESULT:

When reviewing Models at the swagger URL, Foo should look as follows:

description: | My foo class
-- | --
bar | stringIdentifies Describes bars
Enum:[ SomeValue description: A special value ]

ACTUAL RESULT:

description: | My foo class
-- | --
bar | stringIdentifies Describes bars
Enum:[ SomeValue ]

ADDITIONAL DETAILS

[Justin-Lessard]

Since there is no fix yet, I'll post what I did to workaround the issue.

I've created a simple Schema filter that apply to all enum, and simply build the description.

It boils down to this:

public class EnumDescriptorSchemaFilter : ISchemaFilter
{
    public void Apply(Schema schema, SchemaFilterContext context)
    {
        var typeInfo = context.SystemType.GetTypeInfo();
        if (typeInfo.IsEnum)
            schema.Description = BuildDescription(typeInfo);
    }

    private static string BuildDescription(TypeInfo typeInfo)
    {
        // (...)
    }

}

The full implementation is available on my repo.

Then, just add it as a filter in your startup class.

services.AddSwaggerGen(c =>
{    /* (...) */
    c.SchemaFilter<EnumDescriptorSchemaFilter>();
});

Results before applying the filter

"TestEnum": {
  "enum": [
    "Value01",
    "Value02"
  ],
  "type": "string"
}

Results after applying the filter

"TestEnum": {
  "description": "Description of TestEnum\r\n\r\n* `Value01` - Description of value 01\r\n* `Value02` - Description of value 02\r\n",
  "enum": [
    "Value01",
    "Value02"
  ],
  "type": "string"
}

Still not perfect, but it's better than nothing.

The repo is available here should someone need it.

[pfaustinopt]

@Justin-Lessard this line is not working with Swashbuckle.AspNetCore v5.1.0:
var typeInfo = context.SystemType.GetTypeInfo();

[TobiasWenzel]

See also:

739

891

[tahazayed]

@pfaustinopt
try this one
var typeInfo = context.Type.GetTypeInfo();

[icnocop]

As a work-around, I was able to re-use the code here:
https://www.codeproject.com/Articles/5300099/Description-of-the-Enumeration-Members-in-Swashbuc