ASP.NET Core 中如何使用 Swagger UI 浏览和测试 API

Swagger UI 是一个开源工具，用于可视化地浏览、测试和文档化 API。在 ASP.NET Core 中使用 Swagger UI 可以方便地查看和测试 API 的请求和响应。

本文将介绍如何在 ASP.NET Core 项目中集成 Swagger UI，并使用它来浏览和测试 API。

步骤一：安装 Swagger UI

首先，我们需要使用 NuGet 包管理器或者 dotnet CLI 将 Swagger UI 添加到项目中。打开命令行，切换到项目根目录，执行以下命令：

dotnet add package Swashbuckle.AspNetCore

这会将 Swagger UI 的最新版本添加到项目中。

步骤二：配置 Swagger UI

接下来，在 Startup.cs 类中找到 ConfigureServices 方法，并添加以下代码：

using Microsoft.OpenApi.Models;
using Swashbuckle.AspNetCore.SwaggerUI;

public void ConfigureServices(IServiceCollection services)
{
    // ...

    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "API 文档", Version = "v1" });
    });
}

在这个示例中，我们添加了一个“v1”版本的 API 文档。你可以根据需要添加其他版本。

然后，在 Configure 方法中添加以下代码：

using Microsoft.AspNetCore.Builder;
using Swashbuckle.AspNetCore.Swagger;

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ...

    app.UseSwagger();
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "API V1");
        c.RoutePrefix = string.Empty;
        c.DocExpansion(DocExpansion.List);
    });

    // ...
}

这里我们使用了UseSwagger和UseSwaggerUI中间件来启用 Swagger UI，并将 Swagger UI 所需的配置设置为 /swagger/v1/swagger.json，以便从该位置加载 API 文档。

同时，我们将RoutePrefix设置为空字符串，这样 Swagger UI 就可以在项目的根路径上访问。

步骤三：生成 API 文档

现在，我们已经配置了 Swagger UI，接下来我们需要使用 Swagger 来生成 API 文档。

在你的控制器类中，可以添加一些 Swagger 特性来描述 API 的信息，比如路由、HTTP 方法、请求参数等等。

以下是一个示例控制器类的代码：

using Microsoft.AspNetCore.Mvc;

namespace MyProject.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class UsersController : ControllerBase
    {
        [HttpGet]
        [ProducesResponseType(typeof(IEnumerable<string>), 200)]
        public IActionResult Get()
        {
            // API 逻辑
            // 返回一个字符串列表

            return Ok(new List<string> { "User 1", "User 2" });
        }
    }
}

在这个示例中，我们使用了[HttpGet]特性来指定 API 方法的 HTTP 方法。同时，我们使用了[ProducesResponseType]特性来指定该方法的响应类型为一个字符串列表。

重要的是，你可以根据自己的需要在你的 API 方法上添加各种 Swagger 特性来描述 API 的细节，如参数、响应类型、路由等等。

步骤四：浏览和测试 API

现在，启动你的 ASP.NET Core 项目。在浏览器中，输入http://localhost:5000/swagger即可打开 Swagger UI。

Swagger UI 会根据你编写的 Swagger 特性和配置，自动生成一个可视化的文档和测试界面。

在 Swagger UI 中，你可以看到所有添加了 Swagger 特性的 API，并且可以浏览和测试它们。你可以在 Swagger UI 的界面上执行各种操作，例如输入请求参数、发送请求并查看响应等。

结论

在本文中，我们学习了如何在 ASP.NET Core 项目中使用 Swagger UI 来浏览和测试 API。我们首先安装了 Swagger UI 包，然后配置了 Swagger UI，生成了 API 文档，并最终在浏览器中打开了 Swagger UI 来浏览和测试我们的 API。

Swagger UI 不仅提供了一个方便的方式来文档化 API，而且还可以通过测试界面快速、直观地测试 API。这对于开发人员来说是非常有用的，同时也使 API 的使用者更容易理解和使用 API。

希望本文对你了解和使用 ASP.NET Core 中的 Swagger UI 有所帮助！