Documentation of Enums

[LodewijkSioen]

I have a model with an enum.

public class Model
{
    ///<summary>Current State</summary>
    public StatusValues Status {get;set;}
}

This enum is annotated with xml-comments.

///<summary>Possible state values</summary>
public enum StatusValues
{
    ///<summary>This is On</summary>
    On,
    ///<summary>This is Off</summary>
    Off,
    ///<summary>We simply don't know</summary>
    Unknown
}

This results in the following json info:

"Status":{
    "description":"Current State",
    "enum":["On","Off","Unknown"],
    "type":"string"
}

I would like to see the annotations of the enumvalues in the swagger json. There is a proposal on the Open Spec to support this, but nothing official. For now I would be happy to have a way to add the descriptions of the enumvalues to the description of the model property. Like this, for example:

"Status":{
    "description":"Current State
        * `On` - This is On
        * `Off` - This is Off
        * `Unknown` - We simply don't know",
    "enum":["On","Off","Unknown"],
    "type":"string"
}

I've played around with all kinds of filters, but the only thing I can find to do something like this is using MapType<> for each enum individually. But that doesn't really scale.

Am I missing something, or do you accept a pull request to add this?

[LodewijkSioen]

So, I've tried to make it work with an ISchemaFilter, but sadly this filter is called before the XML info is added, so everything gets overridden. In the end, I resorted to writing an IModelFilter and adding that via Reflection because all the ModelFilter methods are internal. This worked.

private static void ModelFilter(this SwaggerDocsConfig config, Func<IModelFilter> factory)
{
    var method = config.GetType().GetMethods(BindingFlags.NonPublic | BindingFlags.Instance)
        .First(m => m.Name == nameof(ModelFilter) && !m.ContainsGenericParameters);
     method.Invoke(config, new object[] { factory });
}

When will the ModelFilter methods be opened up?

[domaindrivendev]

Under the hood, IncludeXmlComments just wires up an operation filter and a schema filter. So, if you apply your Schema filter after that call, it should happen in the desired order.

However, Schema Filters are currently only applied to "object" schema's and therefore won't execute against an "enum" schema. There is a PR that's close to being merged that will apply schema filters everywhere: #799

Once this is in place, your task should be fairly straightforward

[andrewdmoreno]

@LodewijkSioen Did you ever get an implementation working with ISchemaFilter? Would be interested to see your approach as I am facing a similar challenge.

[LodewijkSioen]

Well, I think we used the reflection as described above, but I would need to check this. Let me get back to you.

[LodewijkSioen]

We just used the code as above. The EnumFilter itself looks like this:

foreach (var enumProperty in context.SystemType.GetProperties(BindingFlags.Public | BindingFlags.Instance).Where(p => p.PropertyType.IsEnum))
{
    var schemaProperty = model.properties[enumProperty.Name.ToCamelCase()];

    var builder = new StringBuilder(schemaProperty.description);

    builder.AppendLine();
    //Do work
    schemaProperty.description = builder.ToString();
}

[domaindrivendev]

See PR #799 which adds support to apply schema filters on all schema types, including enums. This will make it very simple to resolve this issue with a simple Schema Filter that enhances all enum descriptions.

It's worth noting that in this version of SB, you'll need explicitly opt in to this behavior with the ApplyFiltersToAllSchemas config settting.

[RobThree]

I'm unclear on if there now is a ("built-in") way in Swashbuckle to document enum descriptions or if I have to implement an ISchemaFilter. What would, currently, be the best way to get enum descriptions documented by Swashbuckle? And I'm assuming I would need to use the ///<summary>...</summary> method? Or could I also use a [Description] attribute?

[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