Question

在我们的ASP.NET Core 2.2项目中有枚举，如下所示：

AVG(Totals) AS [Avg]

我们以这样的方式使用它们：

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

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

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

最后，我们执行services.AddSwaggerGen(c => { c.IncludeXmlComments(GetXmlCommentsPath(), includeControllerXmlComments: true); // etc. });以可视化JSON文件。

问题：app.UseReDoc(c => ...)枚举本身及其选项的xml注释都不会出现在我们文档的任何地方。它也不在OpenAPI JSON文档中（因此从逻辑上讲，它也不会显示在ReDoc中）。

如何将这类文档添加到OpenAPI JSON中，然后再添加到ReDoc页面中？

Answer 1

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

要概括该线程，OP要求与问题中描述的功能相同。后来，提出了两种可能性：

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

第一个选项结果为impossible（规范中没有这样的位置）。第二个选项是rejected。

因此，简而言之：不可能做到。

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

1 个答案: