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

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

2 голосов
/ 17 апреля 2019

В нашем проекте 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?

1 Ответ

1 голос
/ 24 апреля 2019

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

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

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

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

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

...