Include XML Comments for enums in Swagger and ReDoc based OpenAPI documentation

Question

We have enums in our ASP.NET Core 2.2 project, commented on, like these:

/// <summary>Theme for the UI</summary>
public enum Theme
{
    /// <summary>Dark backgrounds, lighter texts</summary>
    Dark,
    /// <summary>Light backgrounds with dark texts</summary>
    Light,
    /// <summary>Colors picked specifically to improve contrasts</summary>
    HighContrast,
}

And we use them for example like this:

/// <summary>UI settings DTO</summary>
public class Settings 
{
    /// <summary>UI theme</summary>
    public Theme Theme { get; set; }
}

/// <summary>Change your settings</summary>
/// <param name="settings">Updated settings</param>
/// <returns>No content</returns>
[HttpPost("/change-settings")]
public async Task<ActionResult> ChangeSettings(Settings settings)
{
    this.themeService.changeTo(settings.Theme);
    // etc.
    return new NoContent();
}

The XML Comments are generated upon build, included as a resource, and made part o the OpenAPI specification like this:

services.AddSwaggerGen(c =>
{
    c.IncludeXmlComments(GetXmlCommentsPath(), includeControllerXmlComments: true);
    // etc.
});

Finally, we do app.UseReDoc(c => ...) to visualize the JSON file.

The problem: xml comments for neither the Theme enum itself, nor its options, shows up anywhere in our documentation. It's not in the OpenAPI JSON document either (so logically it doesn't show up in ReDoc).

How can you get this kind of documentation into your OpenAPI JSON, and next into the ReDoc pages?

Answer 1

I found an issue on GitHub that asks for this as a feature request.

To summarize that thread, OP there requests the same feature as described in the question. Later, two possibilities are suggested:

1. Find a place in the swagger spec where these docs belong
2. Have Swashbuckle do some string concatenation and add the enum descriptions to appropriate places (eg properties that use the enum)

The first option turned out impossible (no such place in the spec). The second option was rejected .

So, in short: what you want is not possible .