Documentation of Enums

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?

[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: https://github.com/domaindrivendev/Swashbuckle/pull/799

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

[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