Как задокументировать аутентификацию ключа API с помощью Swashbuckle.AspNetCore v5.0.0-rc2

Question

Я переношу веб-API, в котором есть документация Swagger, созданная с помощью Swashbuckle, с.NET Framework на ASP.NET Core. В новой версии AspNetCore я использую Swashbuckle.AspNetCore v5.0.0-rc2.

Это внутренняя служба, и для аутентификации используется ключ API, указанный в настраиваемом заголовке HTTP. В приложении.NET Framework я настроил Swashbuckle для включения моего ключа API следующим образом:

c.ApiKey("apiKey")
   .Description("My description")
   .Name("MyHttpHeaderName")
   .In("header);

а также

c.EnableApiKeySupport("MyHtpHeaderName", "header);

Как включить поддержку одного и того же ключа API с помощью Swashbuckle.AspNetCore v5.0.0-rc2?

Большая часть информации, которую я нашел при поиске, похоже, относится к версиям Swashbuckle.AspNetCode до v5.0.0-rc2.

Этот ответ предназначен для v5.0.0-rc2, но охватывает только авторизацию на предъявителя и, похоже, не связан с использованием настраиваемого HTTP-заголовка: /questions/48347105/migratsiya-v-swashbuckleaspnetcore-versii-5/55203461#55203461

Answer 1

В Swashbuckle.AspNetCore, настройка авторизации выполняется с помощью AddSecurityDefinition метод.

В 4.x вы могли настроить ApiKeyScheme который описывает, как использовать ключ API для авторизации запросов:

c.AddSecurityDefinition("ApiKey", new ApiKeyScheme()
{
    Description = "My description",
    Name = "MyHttpHeaderName",
    In = "header",
});

Начиная с 5.x, Swashbuckle.AspNetCore больше не использует свои собственные модели, а вместо этого полагается на OpenAPI.NET. Это означает, что приведенное выше определение безопасности в версии 5.x будет выглядеть так:

c.AddSecurityDefinition("ApiKey", new OpenApiSecurityScheme()
{
    Type = SecuritySchemeType.ApiKey,
    In = ParameterLocation.Header,
    Name = "MyHttpHeaderName",
    Description = "My description",
});

Обратите внимание, что вам также необходимо установить требования безопасности, чтобы указать, какое определение безопасности требуется для каких операций. В 5.x синтаксис для этого будет выглядеть так:

c.AddSecurityRequirement(new OpenApiSecurityRequirement
{
    {
        new OpenApiSecurityScheme
        {
            Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "ApiKey" }
        },
        new string[] { }
    }
});

Подробнее обо всем этом вы можете прочитать в документации по определениям безопасности и требованиям.