Как передать пользовательские заголовки при вызове веб-api с помощью Swagger (Swashbuckle)

Мы используем Swashbuckle для документирования нашего веб-apis и использования его для тестирования нашего веб-авиза. Я хочу знать, как можно передавать несколько пользовательских заголовков с разными значениями для каждого запроса с использованием пользовательского интерфейса Swagger.

Я видел ответ, подобный ниже в Интернете, чтобы передать заголовок в пользовательском интерфейсе Swagger, но не смог оторвать его. Что путает насчет файла SwaggerExtensions. Какова цель этого файла и почему упоминается этот файл в квалифицированном имени js файла.

1. Добавьте новый файл с именем "SwaggerExtensions", а затем добавьте новый JS файл с именем "onComplete.js", вам нужно изменить действие сборки для этого файла на "Embedded Resource".

2. Внутри файла "onComplete.js" вставьте следующий код:

$('#input_apiKey').change(function () {

var key = $('#input_apiKey')[0].value;
if (key && key.trim() != "") {
key = "Bearer " + key;
window.authorizations.add("key", new ApiKeyAuthorization("Authorization",   key, "header"));
}
});

3.Откройте файл "SwaggerConfig.cs" и внутри метода register вставьте следующий код:

SwaggerUiConfig.Customize(c =>
{
 c.SupportHeaderParams = true;
 c.InjectJavaScript(typeof(SwaggerConfig).Assembly,        "AngularJSAuthentication.API.SwaggerExtensions.onComplete.js");
});

Ответ 1

Swashbuckles реализация swagger читает комментарии XML-кода для генерации требуемой спецификации swagger. К сожалению, если вам нужен заголовок авторизации (токен доступа) для запросов, комментарии кода XML не предоставляют эту информацию Swashbuckle. Вам придется вручную вводить этот новый параметр во время генерации спецификации swagger.

Swashbuckle предоставляет интерфейс IOperationFilter для применения новых параметров. Реализация этого интерфейса будет выглядеть примерно так.

public class AddAuthorizationHeaderParameterOperationFilter: IOperationFilter
{
    public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
    {
        var filterPipeline = apiDescription.ActionDescriptor.GetFilterPipeline();
        var isAuthorized = filterPipeline
                                         .Select(filterInfo => filterInfo.Instance)
                                         .Any(filter => filter is IAuthorizationFilter);

        var allowAnonymous = apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute>().Any();

        if (isAuthorized && !allowAnonymous)
        {
            operation.parameters.Add(new Parameter {
                name = "Authorization",
                @in = "header",
                description = "access token",
                required = true,
                type = "string"                    
            });
        }
    }
}

Внутри вашего файла SwaggerConfig.cs добавьте следующий

public class SwaggerConfig
{
    public static void Register()
    {
        var thisAssembly = typeof(SwaggerConfig).Assembly;

        GlobalConfiguration.Configuration
            .EnableSwagger(c =>


                c.SingleApiVersion("v1", "API").Description("An API ")
                                                        .TermsOfService("Some terms")
                                                        .Contact(cc => cc.Name("Team")
                                                        .Email("[email protected]"));

                c.OperationFilter(() => new AuthorizationHeaderParameterOperationFilter()));


      }
 }

Ответ 2

Swashbuckle предлагает использовать InjectJavaScript для выполнения этого. https://github.com/domaindrivendev/Swashbuckle#injectjavascript

Я использую следующий код для добавления маркера-носителя для авторизации в http-заголовке.

httpConfiguration
.EnableSwagger(c => c.SingleApiVersion("v1", "A title for your API")) co
.EnableSwaggerUi(c =>
    {
        c.InjectJavaScript(containingAssembly, "ProjectName.SwaggerUIEnableBearerToken.js");
    });

SwaggerUIEnableBearerToken.js

$(function () {
$('#input_apiKey').attr("placeholder", "bearer token");
$('#input_apiKey').off();
$('#input_apiKey').change(function () {
    var token = this.value;
    if (token && token.trim() !== '') {
        token = 'Bearer ' + token;
        var apiKeyAuth = new window.SwaggerClient.ApiKeyAuthorization("Authorization", token, "header");
        window.swaggerUi.api.clientAuthorizations.add("token", apiKeyAuth);
        }
    }
});
})();

Подробнее об этом выпуске: https://github.com/domaindrivendev/Swashbuckle/issues/222

Ответ 3

Вы можете добавить параметр с помощью SwaggerUI:

swaggerUi.api.clientAuthorizations.add("key", new SwaggerClient.ApiKeyAuthorization("api_key", key, "header"));

Ответ 4

Я наткнулся на этот вопрос при попытке добавить пользовательский заголовок, содержащий некоторую информацию для аутентификации. В этой статье предлагается способ сделать это без внедрения JavaScript (чистый подход.NET), предоставив SecurityDefinition при настройке интеграции Swagger:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1.0", new Info { Title = "Main API v1.0", Version = "v1.0" });

    // Swagger 2.+ support
    var security = new Dictionary<string, IEnumerable<string>>
    {
        {"Bearer", new string[] { }},
    };

    c.AddSecurityDefinition("Bearer", new ApiKeyScheme
    {
        Description = "JWT Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\"",
        Name = "Authorization",
        In = "header",
        Type = "apiKey"
    });
    c.AddSecurityRequirement(security);
});

Это всегда для определения токена безопасности на уровне API или уровне метода (своего рода вход в систему), и этот токен будет использоваться для всех последующих запросов до выхода из системы.