开源地址

Github：https://github.com/swagger-api/swagger-ui (opens new window)

Swagger 是一个用于构建、文档化和测试 RESTful Web API 的开源工具。在 .NET 中，可以使用 Swagger 来自动生成 API 文档，让 API 的使用变得更加方便和易懂。本文将介绍如何在 .NET 中使用 Swagger，并提供详细的使用示例。

安装 Swagger

在 .NET 中使用 Swagger，首先需要安装 NuGet 包。打开 Visual Studio，右键点击项目，选择“管理 NuGet 包”，在“浏览”选项卡中搜索“Swashbuckle.AspNetCore”，点击“安装”按钮进行安装。

配置 Swagger

安装完 NuGet 包后，需要进行配置。在 Startup.cs 文件中添加以下代码：

public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    });
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
    });
}

上面的代码中，ConfigureServices 方法用于配置 Swagger，Configure 方法用于设置 Swagger UI。SwaggerDoc 方法指定了 API 的标题和版本号，SwaggerEndpoint 方法指定了 Swagger UI 的入口点。

添加 Swagger 注释

为了让 Swagger 自动生成 API 文档，需要在 API 控制器中添加注释。在方法上方添加注释，示例如下：

/// <summary>
/// 获取所有用户
/// </summary>
/// <returns>用户列表</returns>
[HttpGet]
public ActionResult<IEnumerable<User>> GetAll()
{
    var users = _userRepository.GetAll();
    return Ok(users);
}

在注释中可以添加参数说明、返回值说明等。Swagger 会根据这些注释自动生成 API 文档。

查看 API 文档

完成上述配置后，可以启动项目并访问 /swagger 路径查看 API 文档。Swagger UI 会显示所有 API 的列表，包括每个 API 的参数、返回值等信息。可以在 Swagger UI 中测试 API，直接输入参数进行测试。

添加 Swagger 安全验证

Swagger 也支持在 API 中添加安全验证，保证 API 的安全性。在 Startup.cs 文件中添加以下代码：

public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
        c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
        {
            Description = "JWT Authorization header using the Bearer scheme.",
            Type = SecuritySchemeType.Http,
            Scheme = "bearer"
        });
        c.AddSecurityRequirement(new OpenApiSecurityRequirement
        {
            {
                new OpenApiSecurityScheme
                {
                    Reference = new OpenApiReference
                    {
                        Type = ReferenceType.SecurityScheme,
                        Id = "Bearer"
                    }
                },
                new string[] { }
            }
        });
    });
}

上面的代码中，AddSecurityDefinition 方法添加了一个名为 Bearer 的安全定义，AddSecurityRequirement 方法添加了一个安全需求，指定了使用 Bearer 安全验证。在需要进行安全验证的 API 上方添加 [Authorize] 标记，示例如下：

/// <summary>
/// 获取当前用户信息
/// </summary>
/// <returns>用户信息</returns>
[HttpGet("me")]
[Authorize]
public ActionResult<User> GetMe()
{
    var user = _userRepository.GetByUserName(User.Identity.Name);
    return Ok(user);
}

上面的代码中，[Authorize] 标记指定了需要进行安全验证。

自定义 Swagger 文档

在默认情况下，Swagger 会自动生成 API 文档。如果需要自定义 API 文档，可以在 Startup.cs 文件中添加以下代码：

public void ConfigureServices(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
        c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "MyApi.xml"));
        c.OperationFilter<AddResponseHeadersFilter>();
    });
}

上面的代码中，IncludeXmlComments 方法指定了 XML 注释文件的路径，用于生成 API 文档。OperationFilter 方法指定了自定义的操作过滤器，用于添加响应头。

总结

Swagger 是一个非常方便的 API 文档工具，在 .NET 中的使用也非常简单。在本文中，我们介绍了如何安装 Swagger、配置 Swagger、添加 Swagger 注释、查看 API 文档、添加 Swagger 安全验证、自定义 Swagger 文档等内容，希望能够对您有所帮助。