.NET Core 的 Swagger 接口文档使用教程

.NET Core 是一个跨平台的开发框架，它可以用于构建各种类型的应用程序，包括 Web API。Web API 是一种基于 HTTP 的服务，它可以提供数据和功能给客户端应用程序，如浏览器、移动设备或其他服务器。为了让客户端应用程序更容易地理解和使用 Web API，我们需要提供一种描述 Web API 的文档，这就是 Swagger（或 OpenAPI）的作用。

Swagger（或 OpenAPI）是一种用于描述 REST API 的语言无关规范。它可以让计算机和人类在不直接访问源代码的情况下，理解 REST API 的功能和参数。它的主要目标是：

• 减少连接解耦服务所需的工作量。

• 减少准确记录服务所需的时间。

Swagger 规范是一个 JSON 格式的文档，它定义了 API 的基本信息、路径、操作、参数、响应和模式等内容。Swagger UI 是一个基于 Web 的工具，它可以根据 Swagger 规范生成一个可视化和交互式的界面，让用户可以浏览和测试 API。

在 .NET Core 中，有两个主要的 OpenAPI 实现，分别是 Swashbuckle 和 NSwag。在本教程中，我们将使用 Swashbuckle 来生成和展示 Swagger 文档。

首先，我们需要创建一个 .NET Core Web API 项目，并安装 Swashbuckle.AspNetCore 包。我们可以使用 Visual Studio、Visual Studio Code 或 .NET Core CLI 来完成这些步骤。安装好 Swashbuckle.AspNetCore 包后，我们需要在 Program.cs 中添加和配置 Swagger 生成器和中间件。Swagger 生成器可以从路由、控制器和模型直接生成 SwaggerDocument 对象，并公开为 JSON 终结点。Swagger 中间件可以为生成的 JSON 文档和 Swagger UI 提供服务。

在 Program.cs 中，我们需要添加以下代码：

using Microsoft.OpenApi.Models; // 导入命名空间

builder.Services.AddControllers(); // 添加控制器服务
builder.Services.AddEndpointsApiExplorer(); // 添加终结点 API 浏览器服务
builder.Services.AddSwaggerGen(options => // 添加 Swagger 生成器服务
{
    options.SwaggerDoc("v1", new OpenApiInfo // 配置 Swagger 文档信息
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });
});

var app = builder.Build();

if (app.Environment.IsDevelopment()) // 判断是否为开发环境
{
    app.UseSwagger(); // 启用 Swagger 中间件
    app.UseSwaggerUI(options => // 启用 Swagger UI 中间件
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1"); // 配置 Swagger 终结点
        options.RoutePrefix = string.Empty; // 设置路由前缀为空字符串
    });
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

启动应用后，我们可以在 https://localhost:<port>/swagger/v1/swagger.json 看到生成的 Swagger 规范文档，如下所示：

{
  "openapi": "3.0.1",
  "info": {
    "title": "ToDo API",
    "version": "v1",
    "description": "An ASP.NET Core Web API for managing ToDo items",
    "termsOfService": "https://example.com/terms",
    "contact": {
      "name": "Example Contact",
      "url": "https://example.com/contact"
    },
    "license": {
      "name": "Example License",
      "url": "https://example.com/license"
    }
  },
  "paths": {
    "/api/Todo": {
      "get": {
        "tags": [
          "Todo"
        ],
        "operationId": "ApiTodoGet",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              },
              "text/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ToDoItem"
                  }
                }
              }
            }
          }
        }
      },
      // 省略其他操作
    },
    "/api/Todo/{id}": {
      // 省略其他操作
    }
  },
  // 省略其他内容
}

Swagger UI 提供了一个可视化和交互式的方式来浏览和测试 API。我们可以选择方法名称来展开区段，添加任何必要的参数，然后选择“试用！”按钮。Swagger UI 会显示请求的 URL、响应状态码、响应头和响应正文等信息。

通过 Swagger UI，我们可以更方便地了解和使用 Web API，也可以更容易地与其他客户端应用程序或服务集成。

除了生成和展示 Swagger 文档，我们还可以自定义和扩展 Swagger 的功能，例如：

• 添加 XML 注释来提供更多的说明和注释。

• 应用过滤器和操作来修改或增强 SwaggerDocument 对象。

• 使用 Swashbuckle.AspNetCore.Annotations 包来启用和丰富响应、架构和参数元数据。

• 使用 Swashbuckle.AspNetCore.ReDoc 包来提供另一种基于 Web 的文档工具 ReDoc。

• 使用 Swashbuckle.AspNetCore.Cli 包来生成静态 Swagger 文件。