2

我们的 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 页面？

4

1 回答 1

1

我在 GitHub 上发现了一个问题，要求将此作为功能请求。

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

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

第一个选项被证明是不可能的（规范中没有这样的地方）。第二个选项被拒绝了。

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

于 2019-04-24T11:57:19.893 回答