c# - 在基于 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 注释都没有出现在我们文档中的任何位置。它也不在 OpenAPI JSON 文档中(因此从逻辑上讲它不会出现在 ReDoc 中)。

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

Answer 1

我找到了 an issue on GitHub要求将此作为功能请求。

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

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

第一个选项结果是impossible (规范中没有这样的地方)。第二个选项是 rejected .

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