Документация Swagger с внешними библиотеками

Использование нескольких библиотек для разделения кода для будущих случаев — это хорошо. Лично мне нравится это делать, если я могу разделить свою логику, чтобы ее можно было повторно использовать в других проектах или частях проектов.

По крайней мере, для меня необходимо разделить модели данных, включая Entity Framework, чтобы на них можно было ссылаться и использовать в Console application, Blazor application или API.

Давайте посмотрим на пример того, как я это делаю. Это снимок экрана проекта, в котором есть несколько приложений и общая библиотека со всеми моделями.

Это пример класса, который я перенес из проекта API с документацией с summary по каждому свойству и классу.

[[[ТОК_7]]]

Если мы ссылаемся на Console application и начинаем использовать модель, мы можем увидеть документацию, это стандартная функция в Visual Studio, поэтому она работает нормально, как вы можете видеть здесь:

Но затем, если мы ссылаемся на API и переходим к Swagger, сводной документации не будет.

Как нам это исправить?

Во-первых, нам нужно включить XML-комментарии в библиотеке, для этого вам нужно обновить настройки проектов и включить ``:

Это создаст в папке сборки несколько файлов, которые заканчиваются расширением xml, как вы можете видеть здесь:

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

Он использует метод, который есть внутри AddSwaggerGen и называется IncludeXmlComments.

Идея состоит в том, что если у нас есть все файлы xml мы принудительно загрузим их в Swagger.

builder.Services.AddSwaggerGen(s =>
{
    // Comments
    var allXmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml");

    foreach (string xmlFiles in allXmlFiles)
    {
        s.IncludeXmlComments(xmlFiles);
    }
});

Это прямо сказано: мы получаем файлы xml из каталога сборки и добавляем их с помощью метода IncludeXmlComments.

Теперь мы снова загружаем API и проверяем, можем ли мы увидеть документацию.

И вы видите, что мы видим документацию!

Я надеюсь, что это помогло вам, если у вас есть какие-либо вопросы, не стесняйтесь обращаться ко мне!