Начало работы с Swashbuckle и ASP.NET Core

Примечание.

Создание документов OpenAPI во время сборки с помощью Swashbuckle не поддерживается в .NET 8 и более поздних версиях. Поддерживаемый вариант времени сборки см . в документации по веб-API ASP.NET Core с помощью Swagger /OpenAPI. Создание документов во время выполнения по-прежнему поддерживается в .NET 8.

Swashbuckle состоит из трех ключевых компонентов.

• Swashbuckle.AspNetCore.Swagger: объектная модель Swagger и ПО промежуточного слоя для предоставления объектов SwaggerDocument в виде конечных точек JSON.

• Swashbuckle.AspNetCore.SwaggerGen: генератор Swagger, создающий объекты SwaggerDocument непосредственно из ваших маршрутов, контроллеров и моделей. Как правило, он комбинируется с ПО промежуточного слоя в конечной точке Swagger и автоматически предоставляет Swagger JSON.

• Swashbuckle.AspNetCore.SwaggerUI: встроенная версия средства пользовательского интерфейса Swagger. Оно интерпретирует Swagger JSON и предоставляет удобную настраиваемую среду для описания функциональности веб-API. К нему можно отнести встроенное окружение теста, используемое в открытых методах.

Установка пакета

Swashbuckle можно добавить одним из описанных ниже способов.

Visual Studio

• В окне Консоль диспетчера пакетов

  • Перейдите в раздел Представление>Другие окна>Консоль диспетчера пакетов

  • Перейдите в каталог, в котором .csproj существует файл

  • Выполните следующую команду:

    Install-Package Swashbuckle.AspNetCore -Version 6.5.0
    

• В диалоговом окне Управление пакетами NuGet

  • Щелкните правой кнопкой мыши проект в обозревателе решений>Управление пакетами NuGet
  • В качестве источника пакета выберите "nuget.org".
  • Убедитесь, что параметр "Включить предварительные выпуски" включен.
  • В поле поиска введите "Swashbuckle.AspNetCore".
  • Выберите последний пакет Swashbuckle.AspNetCore на вкладке Обзор и нажмите кнопку Установить.

Visual Studio для Mac

• Щелкните правой кнопкой мыши папку Пакеты на панели решения>Добавление пакетов....
• В раскрывающемся списке Источник в окне Добавление пакетов выберите вариант "nuget.org".
• Убедитесь, что параметр "Показывать пакеты предварительного выпуска" включен.
• В поле поиска введите "Swashbuckle.AspNetCore".
• В области результатов выберите последний пакет Swashbuckle.AspNetCore и нажмите кнопку Добавить пакет.

Visual Studio Code

Во встроенном терминале выполните следующую команду.

dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 6.5.0

Интерфейс командной строки .NET Core

Выполните следующую команду:

dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 6.5.0

Добавление и настройка ПО промежуточного слоя Swagger

Добавьте генератор Swagger в коллекцию служб в методе Program.cs:

builder.Services.AddControllers();

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

Вызов AddEndpointsApiExplorer , показанный в предыдущем примере, требуется только для минимальных API. Дополнительные сведения см . в этой записи StackOverflow.

В том же файле Program.cs разрешите использовать ПО промежуточного слоя для обслуживания созданного документа JSON и пользовательского интерфейса Swagger:

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

Приведенный выше код добавляет ПО промежуточного слоя Swagger только в том случае, если выбрана текущая среда Development (Разработка). Вызов UseSwaggerUI метода включает внедренную версию средства пользовательского интерфейса Swagger.

Запустите приложение и перейдите к файлу https://localhost:<port>/swagger/v1/swagger.json. Появится созданный документ, описывающий конечные точки, как показано в спецификации OpenAPI (openapi.json).

Пользовательский интерфейс Swagger можно найти по адресу https://localhost:<port>/swagger. Изучите API через пользовательский интерфейс Swagger и включите его в другие программы.

Совет

Чтобы предоставить пользовательский интерфейс Swagger в корневом каталоге приложения (https://localhost:<port>/), установите для свойства RoutePrefix пустую строку:

if (builder.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options => // UseSwaggerUI is called only in Development.
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
        options.RoutePrefix = string.Empty;
    });
}

Если вы используете каталоги в службах IIS или на обратном прокси-сервере, задайте для конечной точки Swagger относительный путь с помощью префикса ./. Например, ./swagger/v1/swagger.json. /swagger/v1/swagger.json указывает, что приложение должно искать JSON-файл в реальном корне URL-адреса (с префиксом маршрута, если он используется). Например, используйте функцию https://localhost:<port>/<route_prefix>/swagger/v1/swagger.json вместо https://localhost:<port>/<virtual_directory>/<route_prefix>/swagger/v1/swagger.json.

Примечание.

По умолчанию Swashbuckle генерирует и предоставляет JSON-файл Swagger в версии 3.0 спецификации, которая официально называется "Спецификация OpenAPI". Чтобы обеспечить обратную совместимость, можно предоставлять JSON-файл в формате версии 2.0. Формат 2.0 необходим для интеграции с такими продуктами, как Microsoft Power Apps и Microsoft Flow, которые сейчас поддерживают спецификацию OpenAPI версии 2.0. Чтобы перейти на формат 2.0, задайте свойство SerializeAsV2 в Program.cs следующим образом:

app.UseSwagger(options =>
{
    options.SerializeAsV2 = true;
});

Настройка и расширение

Swagger предоставляет параметры для документирования объектной модели и настройки пользовательского интерфейса в соответствии с вашим фирменным стилем.

Данные и описание API

Действие настройки, передаваемое в метод AddSwaggerGen, можно использовать для добавления сведений об авторе, лицензии и описании.

В Program.cs импортируйте следующие пространства имен для использования в классе OpenApiInfo:

using Microsoft.OpenApi.Models;

С помощью класса OpenApiInfo измените информацию, которая отображается в пользовательском интерфейсе:

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });
});

Пользовательский интерфейс Swagger отображает сведения о версии:

Комментарии XML

XML-комментарии можно включить следующим образом.

Visual Studio

• В обозревателе решений щелкните проект правой кнопкой мыши и выберите команду Edit <project_name>.csproj.
• Добавьте GenerateDocumentationFile в файл .csproj:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Visual Studio для Mac

• В панели решения нажмите Управление и выберите имя проекта. Перейдите в раздел Сервис>Изменить файл.
• Добавьте GenerateDocumentationFile в файл .csproj:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Visual Studio Code

Добавьте GenerateDocumentationFile в файл .csproj:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Интерфейс командной строки .NET Core

Добавьте GenerateDocumentationFile в файл .csproj:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Включение комментариев XML предоставляет отладочную информацию для недокументированных открытых типов и членов. Недокументированные типы и члены указываются в предупреждающем сообщении. Например, следующее сообщение оповещает о нарушении кода предупреждения 1591:

warning CS1591: Missing XML comment for publicly visible type or member 'TodoController'

Чтобы отключить предупреждения на уровне всего проекта, определите разделенный точками с запятой список игнорируемых кодов предупреждений в файле проекта. Добавление кодов предупреждений в $(NoWarn); также применяется к значениям C# по умолчанию.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

Чтобы отключить предупреждения только для определенных элементов, поместите код в директивы препроцессора #pragma warning. Этот подход полезен для кода, который не должен предоставляться с помощью документации ПО API. В следующем примере код предупреждения CS1591 игнорируется для всего TodoContext класса. Применение кода предупреждения можно восстановить в конце определения класса. Укажите несколько кодов предупреждений в списке, разделив их запятыми.

namespace SwashbuckleSample.Models;

#pragma warning disable CS1591
public class TodoContext : DbContext
{
    public TodoContext(DbContextOptions<TodoContext> options) : base(options) { }

    public DbSet<TodoItem> TodoItems => Set<TodoItem>();
}
#pragma warning restore CS1591

Настройте Swagger на использование XML-файла, который создается с помощью приведенных выше инструкций. В Linux и других операционных системах, отличных от Windows, имена и пути файлов могут быть чувствительны к регистру. Например, файл действителен в Windows, TodoApi.XML но не Ubuntu.

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });

    // using System.Reflection;
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

В приведенном выше коде для создания имени XML-файла, соответствующего имени проекта веб-API, используется отражение. Свойство AppContext.BaseDirectory используется для построения пути к XML-файлу. Некоторые функции Swagger (например, схемы входных параметров или методы HTTP и коды ответов из соответствующих атрибутов) работают без использования XML-файла документации. Для большинства функций, включая метод сводки и описания параметров и кодов ответа, использование XML-файла является обязательным.

Добавление комментариев с тройной косой чертой к действию улучшает Swagger UI. Это добавляет описание в заголовок раздела. Добавьте элемент <summary> над действием Delete:

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
[HttpDelete("{id}")]
public async Task<IActionResult> Delete(long id)
{
    var item = await _context.TodoItems.FindAsync(id);

    if (item is null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(item);
    await _context.SaveChangesAsync();

    return NoContent();
}

Пользовательский интерфейс Swagger отображает внутренний текст элемента <summary> в приведенном выше коде:

Пользовательский интерфейс определяется созданной схемой JSON:

"delete": {
    "tags": [
        "Todo"
    ],
    "summary": "Deletes a specific TodoItem.",
    "parameters": [
        {
            "name": "id",
            "in": "path",
            "description": "",
            "required": true,
            "schema": {
                "type": "integer",
                "format": "int64"
            }
        }
    ],
    "responses": {
        "200": {
            "description": "Success"
        }
    }
},

Добавьте элемент <remarks> в документацию по методу действия Create. Он дополняет сведения, указанные в элементе <summary>, и предоставляет более надежный пользовательский интерфейс Swagger. Содержимое элемента <remarks> может включать простой текст, код JSON или XML.

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

Обратите внимание, как эти дополнительные комментарии улучшают пользовательский интерфейс:

Аннотирование данных

Добавьте к модели атрибуты из пространства имен System.ComponentModel.DataAnnotations, чтобы упростить реализацию компонентов пользовательского интерфейса Swagger.

Добавьте атрибут [Required] к свойству Name класса TodoItem.

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

namespace SwashbuckleSample.Models;

public class TodoItem
{
    public long Id { get; set; }

    [Required]
    public string Name { get; set; } = null!;

    [DefaultValue(false)]
    public bool IsComplete { get; set; }
}

Наличие этого атрибута изменяет поведение пользовательского интерфейса и схему базового JSON.

"schemas": {
    "TodoItem": {
        "required": [
            "name"
        ],
        "type": "object",
        "properties": {
            "id": {
                "type": "integer",
                "format": "int64"
            },
            "name": {
                "type": "string"
            },
            "isComplete": {
                "type": "boolean",
                "default": false
            }
        },
        "additionalProperties": false
    }
},

Добавьте к контроллеру API атрибут [Produces("application/json")]. Он позволяет объявить, что действия контроллера поддерживают тип содержимого ответа application/json:

[ApiController]
[Route("api/[controller]")]
[Produces("application/json")]
public class TodoController : ControllerBase
{

В раскрывающемся списке Тип носителя этот тип содержимого выбирается по умолчанию для операций контроллера GET.

Чем больше заметок к данным используется в веб-API, тем более содержательными и полезными становятся пользовательский интерфейс и страницы справки по API.

Описание типов ответов

Разработчиков, использующих веб-API, больше всего интересуют возвращаемые данные — типы ответов и коды ошибок (если они не стандартны). Типы ответов и коды ошибок обозначаются в комментариях к XML и заметках к данным.

Действие Create в случае успеха возвращает код состояния HTTP 201. Код состояния HTTP 400 возвращается в том случае, когда текст отправленного запроса имеет значение NULL. Без надлежащей документации в пользовательском интерфейсе Swagger пользователь не будет знать, чего ожидать. Эту проблему решает добавление строк, выделенных в следующем примере:

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}

Теперь пользовательский интерфейс Swagger четко документирует ожидаемые коды HTTP-ответов.

Соглашения можно использовать в качестве альтернативы явному добавлению элемента [ProducesResponseType] к отдельным действиям. См. сведения см. об использовании соглашений веб-API.

Для поддержки оформления с помощью [ProducesResponseType] пакет Swashbuckle.AspNetCore.Annotations содержит расширения, которые позволяют включить и обогатить метаданные отклика, схемы и параметра.

Настройка пользовательского интерфейса

Стандартный пользовательский интерфейс отличается функциональностью и презентабельностью. Но на страницах документации по API должна быть представлена ваша фирменная символика или тема. Для оформления компонентов Swashbuckle в фирменном стиле необходимо добавить ресурсы для обслуживания статических файлов, а затем построить структуру папок для их размещения.

Включите ПО промежуточного слоя для статических файлов:

app.UseHttpsRedirection();
app.UseStaticFiles();
app.MapControllers();

Чтобы вставить таблицы стилей CSS, добавьте их в папку wwwroot проекта и укажите относительный путь в параметрах ПО промежуточного слоя:

if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options => // UseSwaggerUI is called only in Development.
    {
        options.InjectStylesheet("/swagger-ui/custom.css");
    });
}

Дополнительные ресурсы

• Просмотреть или скачать образец кода (описание загрузки)
• Swagger не распознает комментарии или атрибуты записей
• Улучшение интерфейса разработчика API с помощью документации Swagger