我在 API 中有一些端点 - /user/login、/products。
在 Swagger UI 中，我将 email 和 password 发布到 /user/login，作为回复，我收到了 token 字符串。
然后，我可以从响应中复制令牌，并希望将其用作Authorization 标头值，用于对所有网址（如果存在）的请求，并以/products 为例。
我应该在 Swagger UI 页面的某处手动创建文本输入，然后将令牌放在那里并以某种方式注入请求，还是有工具可以更好地管理它？
【问题讨论】：
标签： api authorization swagger swagger-ui
在 ASP.NET Web API 中，在 Swagger UI 上传入标头的最简单方法是在 IOperationFilter 接口上实现 Apply(...) 方法。
将此添加到您的项目中：
public class AddRequiredHeaderParameter : IOperationFilter
{
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
if (operation.parameters == null)
operation.parameters = new List<Parameter>();
operation.parameters.Add(new Parameter
{
name = "MyHeaderField",
@in = "header",
type = "string",
description = "My header field",
required = true
});
}
}
在SwaggerConfig.cs中，使用c.OperationFilter<T>()从上面注册过滤器：
public static void Register()
{
var thisAssembly = typeof(SwaggerConfig).Assembly;
GlobalConfiguration.Configuration
.EnableSwagger(c =>
{
c.SingleApiVersion("v1", "YourProjectName");
c.IgnoreObsoleteActions();
c.UseFullTypeNameInSchemaIds();
c.DescribeAllEnumsAsStrings();
c.IncludeXmlComments(GetXmlCommentsPath());
c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
c.OperationFilter<AddRequiredHeaderParameter>(); // Add this here
})
.EnableSwaggerUi(c =>
{
c.DocExpansion(DocExpansion.List);
});
}
【讨论】：
你可以在你的请求中添加一个 header 参数，Swagger-UI 会将它显示为一个可编辑的文本框：
swagger: "2.0"
info:
version: 1.0.0
title: TaxBlaster
host: taxblaster.com
basePath: /api
schemes:
- http
paths:
/taxFilings/{id}:
get:
parameters:
- name: id
in: path
description: ID of the requested TaxFiling
required: true
type: string
- name: auth
in: header
description: an authorization header
required: true
type: string
responses:
200:
description: Successful response, with a representation of the Tax Filing.
schema:
$ref: "#/definitions/TaxFilingObject"
404:
description: The requested tax filing was not found.
definitions:
TaxFilingObject:
type: object
description: An individual Tax Filing record.
properties:
filingID:
type: string
year:
type: string
period:
type: integer
currency:
type: string
taxpayer:
type: object
您还可以添加类型为apiKey 的安全定义：
swagger: "2.0"
info:
version: 1.0.0
title: TaxBlaster
host: taxblaster.com
basePath: /api
schemes:
- http
securityDefinitions:
api_key:
type: apiKey
name: api_key
in: header
description: Requests should pass an api_key header.
security:
- api_key: []
paths:
/taxFilings/{id}:
get:
parameters:
- name: id
in: path
description: ID of the requested TaxFiling
required: true
type: string
responses:
200:
description: Successful response, with a representation of the Tax Filing.
schema:
$ref: "#/definitions/TaxFilingObject"
404:
description: The requested tax filing was not found.
definitions:
TaxFilingObject:
type: object
description: An individual Tax Filing record.
properties:
filingID:
type: string
year:
type: string
period:
type: integer
currency:
type: string
taxpayer:
type: object
securityDefinitions 对象定义了安全方案。
security 对象（在 Swagger–OpenAPI 中称为“安全要求”）将安全方案应用于给定上下文。在我们的例子中，我们通过将安全要求声明为顶层来将其应用于整个 API。我们可以选择在单个路径项和/或方法中覆盖它。
这将是指定安全方案的首选方式；它替换了第一个示例中的 header 参数。不幸的是，至少在我目前的测试中，Swagger-UI 没有提供文本框来控制这个参数。
【讨论】：
RequestParse 在 swagger 文档中添加输入字段。该文本文件如何以及在何处添加 `-name: auth` ？
在ASP.NET Core 2 Web API中，使用Swashbuckle.AspNetCore包2.1.0，实现一个IDocumentFilter：
SwaggerSecurityRequirementsDocumentFilter.cs
using System.Collections.Generic;
using Swashbuckle.AspNetCore.Swagger;
using Swashbuckle.AspNetCore.SwaggerGen;
namespace api.infrastructure.filters
{
public class SwaggerSecurityRequirementsDocumentFilter : IDocumentFilter
{
public void Apply(SwaggerDocument document, DocumentFilterContext context)
{
document.Security = new List<IDictionary<string, IEnumerable<string>>>()
{
new Dictionary<string, IEnumerable<string>>()
{
{ "Bearer", new string[]{ } },
{ "Basic", new string[]{ } },
}
};
}
}
}
在 Startup.cs 中，配置安全定义并注册自定义过滤器：
public void ConfigureServices(IServiceCollection services)
{
services.AddSwaggerGen(c =>
{
// c.SwaggerDoc(.....
c.AddSecurityDefinition("Bearer", new ApiKeyScheme()
{
Description = "Authorization header using the Bearer scheme",
Name = "Authorization",
In = "header"
});
c.DocumentFilter<SwaggerSecurityRequirementsDocumentFilter>();
});
}
在 Swagger UI 中，单击“授权”按钮并设置令牌的值。
结果：
curl -X GET "http://localhost:5000/api/tenants" -H "accept: text/plain" -H "Authorization: Bearer ABCD123456"
【讨论】：
还可以将属性 [FromHeader] 用于应在自定义标头中发送的 Web 方法参数（或模型类中的属性）。像这样的：
[HttpGet]
public ActionResult Products([FromHeader(Name = "User-Identity")] string userIdentity)
至少它适用于 ASP.NET Core 2.1 和 Swashbuckle.AspNetCore 2.5.0。
【讨论】：
using System.Web.Http;。
这是 ASP.NET Core Web Api/Swashbuckle 组合的一个更简单的答案，它不需要您注册任何自定义过滤器。第三次是你知道的魅力:)。
将以下代码添加到您的 Swagger 配置将导致出现“授权”按钮，允许您输入要为所有请求发送的不记名令牌。询问时不要忘记将此令牌输入为Bearer <your token here>。
请注意，下面的代码将为任何和所有请求和操作发送令牌，这可能是也可能不是您想要的。
services.AddSwaggerGen(c =>
{
//...
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(new Dictionary<string, IEnumerable<string>>
{
{ "Bearer", new string[] { } }
});
//...
}
通过this thread。
【讨论】：
我最终来到这里是因为我试图根据我添加到我的 API 方法中的 [Authentication] 属性有条件地在 Swagger UI 中添加标题参数。根据@Corcus 在评论中列出的提示，我能够得出我的解决方案，并希望它能对其他人有所帮助。
使用反射，它检查嵌套在apiDescription 中的方法是否具有所需的属性（在我的例子中是MyApiKeyAuthenticationAttribute）。如果是这样，我可以附加我想要的标头参数。
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription) {
if (operation.parameters == null)
operation.parameters = new List<Parameter>();
var attributes = ((System.Web.Http.Controllers.ReflectedHttpActionDescriptor)
((apiDescription.ActionDescriptor).ActionBinding.ActionDescriptor)).MethodInfo
.GetCustomAttributes(false);
if(attributes != null && attributes.Any()) {
if(attributes.Where(x => x.GetType()
== typeof(MyApiKeyAuthenticationAttribute)).Any()) {
operation.parameters.Add(new Parameter {
name = "MyApiKey",
@in = "header",
type = "string",
description = "My API Key",
required = true
});
operation.parameters.Add(new Parameter {
name = "EID",
@in = "header",
type = "string",
description = "Employee ID",
required = true
});
}
}
}
【讨论】：
c.AddSecurityRequirement(new Dictionary<string, IEnumerable<string>> { { "ApiKeyAuth", new string[0] } }); *.com/questions/49908577/…
对于那些使用NSwag 并需要自定义标题的人：
app.UseSwaggerUi3(typeof(Startup).GetTypeInfo().Assembly, settings =>
{
settings.GeneratorSettings.IsAspNetCore = true;
settings.GeneratorSettings.OperationProcessors.Add(new OperationSecurityScopeProcessor("custom-auth"));
settings.GeneratorSettings.DocumentProcessors.Add(
new SecurityDefinitionAppender("custom-auth", new SwaggerSecurityScheme
{
Type = SwaggerSecuritySchemeType.ApiKey,
Name = "header-name",
Description = "header description",
In = SwaggerSecurityApiKeyLocation.Header
}));
});
}
然后，Swagger UI 将包含一个 授权 按钮。
【讨论】：
Golang/go-swagger 示例：https://github.com/go-swagger/go-swagger/issues/1416
// swagger:parameters opid
type XRequestIdHeader struct {
// in: header
// required: true
XRequestId string `json:"X-Request-Id"`
}
...
// swagger:operation POST /endpoint/ opid
// Parameters:
// - $ref: #/parameters/XRequestIDHeader
【讨论】：
更新 OpenAPI 3，库 Swashbuckle.AspNetCore。此来源提供了正确的代码示例：https://codeburst.io/api-security-in-swagger-f2afff82fb8e
与 JWT Bearer 一起使用的正确代码是：
services.AddSwaggerGen(c =>
{
// configure SwaggerDoc and others
// add JWT Authentication
var securityScheme = new OpenApiSecurityScheme
{
Name = "JWT Authentication",
Description = "Enter JWT Bearer token **_only_**",
In = ParameterLocation.Header,
Type = SecuritySchemeType.Http,
Scheme = "bearer", // must be lower case
BearerFormat = "JWT",
Reference = new OpenApiReference
{
Id = JwtBearerDefaults.AuthenticationScheme,
Type = ReferenceType.SecurityScheme
}
};
c.AddSecurityDefinition(securityScheme.Reference.Id, securityScheme);
c.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{securityScheme, new string[] { }}
});
}
我看过一篇文章，其中包含 OpenAPI 2 的类似代码，但由于该示例错过了参考定义，因此浪费了很多时间。这导致 Swashbuckle 生成了不正确的定义并错过了包含 Authorizeation 标头。所以请仔细检查您使用的 OpenAPI 版本。
【讨论】：
免责声明：此解决方案不使用 Header。
如果有人正在寻找一种懒惰的方式（也在 WebApi 中），我建议：
public YourResult Authorize([FromBody]BasicAuthCredentials credentials)
你不是从标题中得到的，但至少你有一个简单的选择。 您始终可以检查对象是否为空并回退到标头机制。
【讨论】：