在基于 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 文件。

问题： xml 对 Theme 枚举本身及其选项的注释都没有出现在我们的文档中的任何地方。它也不在 OpenAPI JSON 文档中（因此逻辑上它不会出现在 ReDoc 中）。

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

Answer 1

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

总而言之，OP 要求与问题中描述的功能相同。后面建议两种可能：

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

第一个选项结果是impossible (no such place in the spec). The second option was rejected。

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

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

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

c#

swagger

swagger-ui

openapi

redoc