在 Swagger .NET Core 中设置授权 - C#

Swagger是一个用于构建，设计和测试RESTful Web服务的工具，支持多种编程语言。在.NET Core中，使用Swagger来描述API应用程序，可以很好地进行API管理，文档生成，以及测试开发，Swagger也需要进行授权设置，以保证API的安全性和数据的完整性。

实现步骤

下面介绍一下如何在Swagger .NET Core 中设置授权：

步骤1：添加Swagger到.NET Core项目

首先，需要将Swagger添加到.NET Core项目中。打开project.json文件，添加对Swashbuckle.AspNetCore NuGet包的引用，可以使用NuGet包管理器或通过手动添加：

{
  "dependencies": {
    "Swashbuckle.AspNetCore": "4.0.1"
  }
}

步骤2：配置Swagger

在.NET Core项目中，需要在Startup.cs文件中配置Swagger，调用ConfigureServices方法：

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    // 配置Swagger
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
    });
}

其中，ConfigureServices方法主要是用于注入Swagger服务，AddSwaggerGen方法注册了Swagger生成器，SwaggerDoc方法用于配置Swagger文档的版本号，可以任意命名（此处为v1）。

步骤3：启用Swagger

在Startup.cs文件中配置Swagger中间件，调用UseSwagger和UseSwaggerUI方法：

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory)
{
    loggerFactory.AddDebug();

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    // 启用Swagger中间件
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });

    app.UseMvc();
}

其中，UseSwagger方法启用Swagger的JSON端点，用于返回Swagger规范，UseSwaggerUI方法将Swagger提供程序在UI中呈现，SwaggerEndpoint参数定义了API的JSON端点名称和文件的版本号（v1）。

步骤4：设置授权

在.NET Core项目中，可以使用OAuth2为API进行授权。首先，在Swagger的配置中使用AddSecurityDefinition方法为API添加安全方案：

c.AddSecurityDefinition("Bearer", new OAuth2Scheme
{
    Type = "oauth2",
    Flow = "password", // 支持password认证方式
    Description = "JWT Authorization header using the Bearer scheme.",
    TokenUrl = "http://localhost:5000/api/auth/token" // 获取Token的地址
});

其中，"Bearer"是自定义的名称，OAuth2Scheme定义了授权方式的类型以及获取Token的地址。

然后，在API的操作中使用Authorize属性进行授权设置：

[HttpGet]
[Authorize(Roles = "admin")] // 设置授权角色
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}

Authorize属性中，Roles属性可以设置授权角色，如果角色不匹配，则会返回401未授权状态码。

最后，在SwaggerUI中可以进行Token的获取，用于进行授权：

总结

本篇文章详细介绍了如何在Swagger .NET Core中进行API的授权设置，包括添加Swagger到.NET Core项目、配置Swagger、启用Swagger和设置授权等步骤，对于进行API管理和安全性方面有一定的帮助。