Включить XML-комментарии для перечислений в документацию OpenAPI на основе Swagger и ReDoc

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 Сам enum и его параметры не обнаруживаются нигде в нашей документации. Его также нет в документе OpenAPI JSON (так что логически он не отображается в ReDoc).

Как вы можете получить такую ​​документацию в вашем OpenAPI JSON, а затем на страницах ReDoc?

Answer 1

Я нашел проблему на GitHub, которая запрашивает это как запрос функции.

Подводя итог этой теме, OP там запрашивает ту же функцию, как описано в вопросе. Позже предлагаются две возможности:

1. Найдите место в спецификации Swagger, где эти документы принадлежат
2. Попросите Swashbuckle выполнить конкатенацию строк и добавить описания перечислений в соответствующие места (например, свойства, использующие перечисление)

Первый вариант оказался невозможным (такого места нет в спецификации). Второй вариант был отклонен.

Итак, вкратце: то, что вы хотите, не возможно.