C#, webAPI, контроллер, swagger: каким атрибутом задаётся комментарий?

Question

C#, webAPI, контроллер, swagger: каким атрибутом задаётся комментарий?

Рейтинг: 1Ответов: 1Опубликовано: 20.03.2023

Жил я себе не тужил, расширял контроллеры своими методами, и писал атрибуты в стиле

    [HtpPost("А этот метод выдаёт отчет номер два!")]
    public async Task<List<string>> GetReport2(){ ... }

и очень радовался, что надпись А этот метод выдаёт отчет номер два! хорошо видна в swagger- интерфейсе.

И тут оказалось, что вообще-то это - имя темплейта, и вообще так писать нельзя.

Что же делать? Видимо, есть какой-то волшебный атрибут, чтобы написать комментарий, и его было видно в сваггере.

Пока просмотрел штук пять "руководств" - нигде про комментарии при помощи атрибутов в контроллерах ни слова.

Может, кто то знает эту магию?

Спасибо!

asp.net-web-api .net asp.net-core swagger

Источник: Stack Overflow на русском

Answer 1

▲ 4Принят

А ларчик просто открывался.

Вот так вот правильно:

    /// <summary> А этот метод выдаёт отчет номер два! </summary>
    [HttpPost("[action]")]
    public async Task<List<string>> GetReport2(){ ... }

Но самое загадочное - что на "чистом" проекте, сделанном "с нуля" командой

    dotnet new webapi

этот метод не работает - надпись в в сваггере не появляется. Когда я в этом убедился - я прочитал разные советы на эту тему, и могу теперь сам ответить на свой вопрос:

Чтобы включить комментарии в сваггер-интерфейс, нужно выполнить 2 действия:

Включить "генерацию документации в формате XML" и
Указать в метода builder.Services.AddSwaggerGen() "включить комментарии из XML в тело генерируемого интерфейса"

Расшифрую. Первый пункт - это просто "галочка" в настройках проекта, см. картинку в конце моего ответа.

Надо сказать, что её установка приводит к тому, что в файл *.csproj дописывается секция:

    <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
      <DocumentationFile>bin\Debug\api1.xml</DocumentationFile>
    </PropertyGroup>

и этот процесс показан на картинке 2.

Второй пункт - означает, что в Program.cs вместо строки

    builder.Services.AddSwaggerGen();

нужно написать что то вроде

    builder.Services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1",
                new OpenApiInfo()
                {
                    Title = "My API - V1",
                    Version = "v1"
                }
            );

            var filePath = Path.Combine(System.AppContext.BaseDirectory, "api1.xml");
            c.IncludeXmlComments(filePath);
        } );

и это изменение показано на картинке 3.

Также, обратите внимание на то, что в пунктах 2 и 3 имя XML файла - одно и то же, то есть "мы генерируем доки в формате XML и потом именно этот XML файл используем при генерации swagger-интерфейса".

При таких условиях - в интерфейса сваггера появляются комментарии, вписанные...

    /// <summary> Вот в такое место! </summary>

Кажется, теперь это полный ответ.

C#, webAPI, контроллер, swagger: каким атрибутом задаётся комментарий?

Ответы