在 NSwag SwaggerUi 中实现 JwtBearer 身份验证

Posted 2023-03-08

【中文标题】在 NSwag SwaggerUi 中实现 JwtBearer 身份验证

【英文标题】：Implement JwtBearer Authentication in NSwag SwaggerUi

【发布时间】：2018-02-24 10:39:43

【问题描述】：

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

如何在 NSwag 提供的 Swagger Ui 中使用 Open ID / JWT？

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

【参考方案1】：

Sample by 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。

【参考方案2】：

我正在使用 NSwag v13.0.6，并在 Startup.Configure 中添加对 UseSwaggerUi3 的 JWT 支持（根据 @Der_Meister 的回答）不再有效。

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

// 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.Security 以解析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 包括 Bearer Authentication 定义。如果您让 NSwag 生成 Swagger 身份验证定义，那么您的里程可能会有所不同。

【讨论】：

这个答案帮助我解决了迁移到 v13 的问题。在 OWIN 的情况下，UseSwaggerUi3 上的第二个参数是 action 所以使用“settings.GeneratorSettings.DocumentProcessors.Add”。

另请注意，SecurityDefinitionAppender 在 12.3 中的 Nswag.SwaggerGeneration 中“已弃用”，并且针对 NSwag Core 的 v13 出现错误（“对类型声明的引用已定义，但无法找到”）。确保您使用的是 NSwag.Generation 之外的 SecurityDefinitionAppender。

【参考方案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"));

成功了。 ConfigureServices中的完整代码：

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();

【参考方案4】：

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

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