在基于 Swagger 和 ReDoc 的 OpenAPI 文档中包含枚举的 XML 注释

Question

我们的 ASP.NET Core 2.2 项目中有枚举，评论如下：

/// <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,
}

例如，我们像这样使用它们：

/// <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();
}

XML 注释在构建时生成，作为资源包含在内，并成为 OpenAPI 规范的一部分，如下所示：

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

最后，我们使用app.UseReDoc(c => ...) 来可视化 JSON 文件。

问题：Theme 枚举本身及其选项的 xml cmets 均未显示在我们文档的任何位置。它也不在 OpenAPI JSON 文档中（所以逻辑上它不会出现在 ReDoc 中）。

如何将此类文档放入 OpenAPI JSON 中，然后放入 ReDoc 页面？

Answer 1

我发现an issue on GitHub 要求将此作为功能请求。

总结该线程，那里的 OP 请求与问题中描述的相同的功能。后来提出了两种可能：

1. 在 swagger 规范中找到这些文档所属的位置
2. 让 Swashbuckle 进行一些字符串连接并将枚举描述添加到适当的位置（例如使用枚举的属性）

第一个选项变成了impossible（规范中没有这样的地方）。第二个选项是rejected。

所以，简而言之：你想要的都是不可能的。