Swashbuckle.aspnetcore: Documentation of Enums

[freeranger]

Hi,

We would like our enum xml comments to appear in our swagger docs but currently they don't.
I found this issue in the WebApi version of Swashbuckle: https://github.com/domaindrivendev/Swashbuckle/issues/739 and was wondering if there is a solution to this yet?

Do we need to do something like: https://github.com/domaindrivendev/Swashbuckle/issues/739#issuecomment-252929052

thanks

[ThisNoName]

If you make the parameter enum type and set describe enum as string, they will show up in swagger documentation. Not sure if that applies to your situation, but it appears to be a more reliable option.

[freeranger]

Hi,

N/A in this case - I already have them appearing as strings but I need the documentation that goes with them to explain what they mean.
Thanks anyway

[markbeij]

Same here. Would love to have the description of possible enum values in Swagger UI

[ThisNoName]

Like this?

[freeranger]

No - I need the individual enum values documented.
So with you example there is probably something like:

    /// <summary>
    /// Invitation Source
    /// </summary>
    public enum Source
    {
        /// <summary>
        /// Source is an Admin
        /// </summary>
        Admin,
        /// <summary>
        /// Source is an Email
        /// </summary>
        Email,
        /// <summary>
        /// Source is Print
        /// </summary>
        Print,
        /// <summary>
        /// Source is something else
        /// </summary>
        Others
    }

What I want to see in the documentation is the descriptions of the individual enum values - so "Source is something else" for "others" etc

[freeranger]

@domaindrivendev Can you offer any thoughts on this? Thanks

[domaindrivendev]

I don't believe the Swagger specification supports descriptions at the enum value level, but I could be wrong. If folks feel strongly enough about this feature, I would suggest starting with the Swagger spec and if you see a suitable place to add this additional metadata, code something up and submit a PR to this repo.

[freeranger]

Thanks, If I am reading this correctly: https://swagger.io/docs/specification/data-models/enums/ then it looks like they are supported.
If I could free up some time to take a look, can you give some pointers on where to start looking to add something to support this?
thanks

[SimonTouchtech]

The Swagger spec does not allow documentation in the enum property because that property is defined as an array of possible values in JSON Schema. What is suggested in the link @freeranger provided is to instead include this documentation in the parameter or property. In their example they set it to

Sort order:
* `asc` - Ascending, from A to Z
* `desc` - Descending, from Z to A

There is no connection in the Swagger specification itself between the asc in the description and the one in the enum array. I guess Swashbuckle could be made to add together the different documentation parts, so the description based on the example above would be

Invitation Source
* `Admin` - Source is an Admin
* `Email` - Source is an Email
* `Print` - Source is Print
* `Other` - Source is something else

I assume this would be possible, but Swashbuckle would need to do some string building and make a decision about the formatting of the description instead of "only" converting it to the OpenAPI format.

[freeranger]

@SimonTouchtech Sorry, you're right - I misread it. Closing this issue since swashbuckle isn't going to introduce features not supported by the swagger spec

[tjgalama]

Regarding the underlying reason seems to be an issue opened within the OpenApi repository : https://github.com/OAI/OpenAPI-Specification/issues/348