Enhancement: Include <summary> comments for enum values
See original GitHub issueIf you call UseReferencedDefinitionsForEnums() in services.AddSwaggerGen() lambda, Xml comments are ignored for enum types.
VERSION:
Swashbuckle.AspNetCore 4.0.1
STEPS TO REPRODUCE:
- Enable a C# web solution as normal with Swashbuckle. You may decide to use DescribeAllEnumsAsStrings() and UseReferencedDefinitionsForEnums(), it doesn’t matter.
- Run app and go to swagger URL.
- 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:
Foo
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
Issue Analytics
- State:
- Created 5 years ago
- Reactions:20
- Comments:6
Top Results From Across the Web
c# - How do I comment a publicly visible type Enum?
Yes I realize that comments are unnecessary, but if commenting is easy and it resolves the warnings then I'd like to do it....
Read more >Enhancing C# Enums
An enum in C# is a value type that is used to represent a set of fixed ... If required, we can extend...
Read more >Enumerated types
Enumerated types, often called enumerations or enums, are a special kind of class used to represent a fixed number of constant values. info...
Read more >object oriented - Enhanced C# Enumeration / `enum`
I'd like to join @HenrikHansen request and ask you too to summarize the features that your smarter-enum is about. You have just posted...
Read more >.NET Core: Writing Really Obvious Code with Enumerated ...
Peter's pretty fanatical about replacing documentation/comments with readable code. So he's very excited about using enums when defining ...
Read more >
Top Related Medium Post
No results found
Top Related StackOverflow Question
No results found
Troubleshoot Live Code
Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free
Top Related Reddit Thread
No results found
Top Related Hackernoon Post
No results found
Top Related Tweet
No results found
Top Related Dev.to Post
No results found
Top Related Hashnode Post
No results found
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:
The full implementation is available on my repo.
Then, just add it as a filter in your startup class.
Results before applying the filter
Results after applying the filter
Still not perfect, but it’s better than nothing.
The repo is available here should someone need it.
Are there plans to implement this?