使用api密钥身份验证的Swagger客户端生成

Question

我有一个现有的C＃ASP.NET Web API 2项目（.NET 4.6.1），在这里我需要集成Swagger来生成文档以及客户端SDK（目前仅C＃）。这是使用Swashbuckle的最新版本（5.5.3）完成的。

除了一件事，其他一切都很顺利。我遇到的问题是，我的SwaggerConfig.cs中定义的安全性（通过HTTP标头通过apiKey）最终出现在输出JSON中，但不知何故未链接到任何方法（即使它是强制性的）。

我的安全性配置定义如下：

GlobalConfiguration.Configuration.EnableSwagger(c =>
{
    c.SingleApiVersion("v1", "Dummy API")
    c.ApiKey("apiKey")
        .Description("API Key Authentication")
        .Name("X-API-Key")
        .In("header");
}).EnableSwaggerUi(c =>
{
    c.EnableApiKeySupport("X-API-Key", "header");
});

以及生成的Swagger JSON中的结果：

"securityDefinitions": {
        "apiKey": {
        "type": "apiKey",
        "description": "API Key Authentication",
        "name": "X-API-Key",
        "in": "header"
    }
}

这是我得到的：

"/api/ping": {
  "get": {
    "tags": [
      "Dummy"
    ],
    "summary": "Ping.",
    "operationId": "ping",
    "consumes": [],
    "produces": [
      "application/json"
    ],
    "responses": {
      "200": {
        "description": "OK",
        "schema": {
          "type": "string"
        }
      }
    }
  }
}

与我想要获得的相比：

"/api/ping": {
  "get": {
    "tags": [
      "Dummy"
    ],
    "summary": "Ping.",
    "operationId": "ping",
    "consumes": [],
    "produces": [
      "application/json"
    ],
    "responses": {
      "200": {
        "description": "OK",
        "schema": {
          "type": "string"
        }
      }
    },
    "security": [
      {
        "apiKey": []
      }
    ]
  }
}

任何想法我应该在项目中进行哪些更改，以便生成security部分？

Answer 1

这个问题和其他问题在帮助我前进的道路上很棒。在我的情况下，我总是只缺少一件事-SwaggerUI并没有在用[Authorize]装饰动作/控制器时将我选择的标头名称/值（X-API-KEY）传递给身份验证处理程序。我的项目使用.NET Core 3.1和Swashbuckle5。我制作了一个自定义类，该类继承了IOperationFilter，该类使用下面的Swashbuckle.AspNetCore.Filters nuget包来支持oauth2的实现。

// Startup.cs
// ...
services.AddSwaggerGen(options =>
{
  options.SwaggerDoc("v1", new OpenApiInfo { Title = nameof(BoardMinutes), Version = "v1" });

  // Adds authentication to the generated json which is also picked up by swagger.
  options.AddSecurityDefinition(ApiKeyAuthenticationOptions.DefaultScheme, new OpenApiSecurityScheme
  {
      In = ParameterLocation.Header,
      Name = ApiKeyAuthenticationHandler.ApiKeyHeaderName,
      Type = SecuritySchemeType.ApiKey
  });

  options.OperationFilter<ApiKeyOperationFilter>();
});

关键组件是options.AddSecurityDefinition()（我有一些开放的端点，不想提供全局过滤器）以及options.OperationFilter<ApiKeyOperationFilter>()。

// ApiKeyOperationFilter.cs
// ...
internal class ApiKeyOperationFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        // Piggy back off of SecurityRequirementsOperationFilter from Swashbuckle.AspNetCore.Filters which has oauth2 as the default security scheme.
        var filter = new SecurityRequirementsOperationFilter(securitySchemaName: ApiKeyAuthenticationOptions.DefaultScheme);
        filter.Apply(operation, context);
    }
}

最后，完整的图片，这里是身份验证处理程序和身份验证选项

// ApiKeyAuthenticationOptions.cs
// ... 
public class ApiKeyAuthenticationOptions : AuthenticationSchemeOptions
{
    public const string DefaultScheme = "API Key";
    public string Scheme => DefaultScheme;
    public string AuthenticationType = DefaultScheme;
}

// ApiKeyAuthenticationHandler.cs
// ...
internal class ApiKeyAuthenticationHandler : AuthenticationHandler<ApiKeyAuthenticationOptions>
{
    private const string ProblemDetailsContentType = "application/problem+json";
    public const string ApiKeyHeaderName = "X-Api-Key";

    private readonly IApiKeyService _apiKeyService;
    private readonly ProblemDetailsFactory _problemDetailsFactory;

    public ApiKeyAuthenticationHandler(
        IOptionsMonitor<ApiKeyAuthenticationOptions> options,
        ILoggerFactory logger,
        UrlEncoder encoder,
        ISystemClock clock,
        IApiKeyService apiKeyService,
        ProblemDetailsFactory problemDetailsFactory) : base(options, logger, encoder, clock)
    {
        _apiKeyService = apiKeyService ?? throw new ArgumentNullException(nameof(apiKeyService));
        _problemDetailsFactory = problemDetailsFactory ?? throw new ArgumentNullException(nameof(problemDetailsFactory));
    }

    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        if (!Request.Headers.TryGetValue(ApiKeyHeaderName, out var apiKeyHeaderValues))
        {
            return AuthenticateResult.NoResult();
        }

        Guid.TryParse(apiKeyHeaderValues.FirstOrDefault(), out var apiKey);

        if (apiKeyHeaderValues.Count == 0 || apiKey == Guid.Empty)
        {
            return AuthenticateResult.NoResult();
        }

        var existingApiKey = await _apiKeyService.FindApiKeyAsync(apiKey);

        if (existingApiKey == null)
        {
            return AuthenticateResult.Fail("Invalid API Key provided.");
        }

        var claims = new List<Claim>
        {
            new Claim(ClaimTypes.Name, existingApiKey.Owner)
        };

        var identity = new ClaimsIdentity(claims, Options.AuthenticationType);
        var identities = new List<ClaimsIdentity> { identity };
        var principal = new ClaimsPrincipal(identities);
        var ticket = new AuthenticationTicket(principal, Options.Scheme);

        return AuthenticateResult.Success(ticket);
    }

    protected override async Task HandleChallengeAsync(AuthenticationProperties properties)
    {
        Response.StatusCode = StatusCodes.Status401Unauthorized;
        Response.ContentType = ProblemDetailsContentType;
        var problemDetails = _problemDetailsFactory.CreateProblemDetails(Request.HttpContext, StatusCodes.Status401Unauthorized, nameof(HttpStatusCode.Unauthorized),
            detail: "Bad API key.");

        await Response.WriteAsync(JsonSerializer.Serialize(problemDetails));
    }

    protected override async Task HandleForbiddenAsync(AuthenticationProperties properties)
    {
        Response.StatusCode = StatusCodes.Status403Forbidden;
        Response.ContentType = ProblemDetailsContentType;
        var problemDetails = _problemDetailsFactory.CreateProblemDetails(Request.HttpContext, StatusCodes.Status403Forbidden, nameof(HttpStatusCode.Forbidden),
            detail: "This API Key cannot access this resource.");

        await Response.WriteAsync(JsonSerializer.Serialize(problemDetails));
    }
}