在 NSwag SwaggerUi 中实现 JwtBearer 身份验证

Question

在我的 asp.net core 2.0 解决方案中，我想添加 Azure AD 身份验证。借助 VS 2017 中的 Azure AD 模板，您可以获得 JWTBearer 身份验证实现或 OpenIdConnect 实现。Open Id 还享有比 OAuth 更安​​全的声誉。

如何将 Open ID / JWT 与 NSwag 提供的 Swagger Ui 一起使用？

我目前的解决方法是允许 OAuth 和 Open Id，但我需要自己实现，并且几乎没有关于新 2.0 API 的文档。具有两个身份验证工作流程也不太安全。特别是当一个比另一个更不安全时。

Answer 1

由renepape 提供的示例：

app.UseSwaggerUi(typeof(Startup).GetTypeInfo().Assembly, settings =>
{
    settings.GeneratorSettings.OperationProcessors.Add(new OperationSecurityScopeProcessor("JWT Token"));

    settings.GeneratorSettings.DocumentProcessors.Add(new SecurityDefinitionAppender("JWT Token",
        new SwaggerSecurityScheme
        {
            Type = SwaggerSecuritySchemeType.ApiKey,
            Name = "Authorization",
            Description = "Copy 'Bearer ' + valid JWT token into field",
            In = SwaggerSecurityApiKeyLocation.Header
        }));
});

它UseSwaggerUi3也适用。

Answer 2

UseSwaggerUi3我正在使用 NSwag v13.0.6，并且使用in添加 JWT 支持Startup.Configure（根据 @Der_Meister 的答案）不再起作用。

AddSwaggerDocument相反，我发现我必须在调用中定义设置Startup.ConfigureServices：

// In the ConfigureServices method -- FWIW my app has this right after services.AddMvc()

services.AddSwaggerDocument(config => {
    config.DocumentProcessors.Add(new SecurityDefinitionAppender("JWT Token",
        new OpenApiSecurityScheme {
            Type = OpenApiSecuritySchemeType.ApiKey,
            Name = "Authorization",
            Description = "Copy 'Bearer ' + valid JWT token into field",
            In = OpenApiSecurityApiKeyLocation.Header
        }));
});

笔记：

• 添加using NSwag.Generation.Processors.Securitytop即可解决SecurityDefinitionAppender
• 所有其他类型解析为using NSwag

那么Startup.Configure你所需要的就是：

app.UseSwaggerUi3();

实际上我的工作代码Startup.Configure与上面的略有不同，因为我使用自定义swagger.json（这是项目要求）：

// Required for serving up a static, hand-rolled JSON file for Swagger doc.
app.UseStaticFiles();
// Specify the custom JSON location.
app.UseSwaggerUi3(settings => settings.DocumentPath = "/swagger/v1/swagger.json");

我的自定义swagger.json包括承载身份验证定义。如果您让 NSwag 生成 Swagger 身份验证定义，那么您的情况可能会有所不同。

Answer 3

您也可以使用 config.AddSecurity ，它似乎更适合它：

services.AddSwaggerDocument(config => {
    config.AddSecurity("JWT token", new OpenApiSecurityScheme
        {
            Type = OpenApiSecuritySchemeType.ApiKey,
            Name = "Authorization",
            Description = "Copy 'Bearer ' + valid JWT token into field",
            In = OpenApiSecurityApiKeyLocation.Header
        });
    config.PostProcess = (document) =>
    {
        document.Info.Version = "v1";
        document.Info.Title = "MyRest-API";
        document.Info.Description = "ASP.NET Core 3.1 MyRest-API";
    };
});

但是，这两种构造都会导致在 Swagger UI 中添加令牌的选项，但不会导致发送 Authorization 标头。当我添加这一行时：

config.OperationProcessors.Add(new OperationSecurityScopeProcessor("JWT token"));

有效。配置服务中的完整代码：

services.AddSwaggerDocument(config => {
    config.OperationProcessors.Add(new OperationSecurityScopeProcessor("JWT token"));
    config.AddSecurity("JWT token", new OpenApiSecurityScheme
        {
            Type = OpenApiSecuritySchemeType.ApiKey,
            Name = "Authorization",
            Description = "Copy 'Bearer ' + valid JWT token into field",
            In = OpenApiSecurityApiKeyLocation.Header
        });
    config.PostProcess = (document) =>
    {
        document.Info.Version = "v1";
        document.Info.Title = "MyRest-API";
        document.Info.Description = "ASP.NET Core 3.1 MyRest-API";
    };
});

并在配置中

app.UseOpenApi();
app.UseSwaggerUi3();

Answer 4

Swagger UI 2.x 的 NSwag 设置非常有限。首先，您需要检查 Swagger UI 如何支持这一点，也许您需要自己托管 Swagger UI，以便可以对其进行更多参数化（并且只需使用 NSwag 生成 Swagger 规范）。

在 NSwag v11.7.2 中，您还可以选择使用 Swagger UI 3.x，也许此版本中支持开箱即用 ( UseSwaggerUi3())。