.NET Core WebAPI 之 Swagger 注释

Swagger 是一种功能强大的开源工具，用于自动生成、描述、展示和可视化 RESTful 的 Web API。在 .NET Core WebAPI 中使用 Swagger 注释可以方便地生成 API 文档，并提供接口测试工具。

为什么使用 Swagger 注释

1. 自动生成 API 文档：Swagger 注释可以根据代码中的注释自动生成 API 文档，减少手动编写文档的工作量。
2. 易于维护：代码注释是与代码一起维护的，这意味着当 API 发生变化时，注释也会相应更新，保持文档的准确性。
3. 提供接口测试工具：Swagger 提供了一个简单易用的界面，可以直接在浏览器中测试 API 接口。

如何在 .NET Core WebAPI 中使用 Swagger 注释

在 .NET Core WebAPI 中使用 Swagger 注释需要安装以下 NuGet 包：

dotnet add package Swashbuckle.AspNetCore

安装完成后，在 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");
    });

    // ...
}

现在，在控制器的方法上添加注释来描述 API 接口，例如：

/// <summary>
/// 获取用户信息
/// </summary>
/// <remarks>返回用户的详细信息</remarks>
/// <param name="id">用户ID</param>
/// <returns>用户信息</returns>
/// <response code="200">返回用户信息</response>
/// <response code="404">找不到用户</response>
[HttpGet("{id}")]
public ActionResult<User> GetUser(int id)
{
    // ...
}

以上注释将用于生成 API 文档，并提供接口测试功能。

Swagger 注释常用标签说明

• <summary>: 用于描述方法的简要介绍。
• <remarks>: 用于提供方法的详细描述信息。
• <param>: 用于描述方法的参数，可指定参数名称，直接在方法参数前添加与标签相同的名称，例如：/// <param name="id">用户ID</param>。
• <returns>: 用于描述方法的返回值。
• <response code="xxx">: 用于描述方法的响应状态码和说明。

结语

通过使用 Swagger 注释，我们可以更加方便地生成和维护 API 文档，并提供接口测试工具，极大地提高了开发效率。希望本文对你理解和使用 Swagger 注释有所帮助。

本文来自极简博客，作者：蔷薇花开，转载请注明原文链接：.NET Core WebAPI 之 Swagger 注释