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

时间:2019-04-17 12:23:05

标签: c# swagger swagger-ui openapi redoc

在我们的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页面中?

1 个答案:

答案 0 :(得分:1)

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

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

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

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

因此,简而言之:不可能做到