Question

我们正在使用Swashbuckle记录我们的网络api并使用它来测试我们的网络api。我想知道如何使用Swagger UI为每个请求传递多个具有不同值的自定义标头。

我在互联网上看到如下答案，在Swagger UI中传递一个标题，但无法理解它。令人困惑的是SwaggerExtensions文件。这个文件的目的是什么？为什么在js文件的限定名称中提到这个文件。

1.添加名为“SwaggerExtensions”的新文件，然后添加名为“onComplete.js”的新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”并在寄存器方法中粘贴下面的代码：

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

Answer 1

Swagbuckles 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("team@team.com"));

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


      }
 }

Answer 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

Answer 3

您可以使用SwaggerUI添加参数：

{{1}}

Answer 4

在尝试添加包含一些身份验证信息的自定义标头时，我偶然发现了这个问题。 This article提出了一种在配置swagger集成时提供SecurityDefinition而不注入JavaScript的方法（纯.NET方法）：

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级别或方法级别（某种形式的登录）定义安全令牌，并且该令牌将用于所有后续请求，直到注销为止。

如何使用Swagger（Swashbuckle）调用web api时传递自定义标头

4 个答案: