ASP.NET Core 中集成 Swagger 为你的 RESTful API 生成文档

在 ASP.NET Core 中集成 Swagger 来为你的 RESTful API 生成文档是一个常见的做法。Swagger（也称为 OpenAPI）允许你使用 JSON 或 YAML 格式来描述 RESTful API，并且提供了 UI 界面来测试和浏览这些 API。

目录

1.安装 NuGet 包

2.配置 Swagger

3.配置 Swagger UI

4.运行和测试

---

以下是如何在 ASP.NET Core 项目中集成 Swagger 的步骤：

1.安装 NuGet 包

Install-Package Swashbuckle.AspNetCore

或者，如果你使用的是 .NET CLI，可以在项目目录中运行：

dotnet add package Swashbuckle.AspNetCore

2.配置 Swagger     

   在 Startup.cs 文件的 ConfigureServices 方法中，添加 Swagger 的服务：

public void ConfigureServices(IServiceCollection services)
{
    // ... 其他服务配置 ...

    services.AddSwaggerGen(options =>
    {
        options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

        // 添加注释（XML 注释）到你的 API 文档
        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        options.IncludeXmlComments(xmlPath);
    });
}

为了生成 XML 注释文件，你需要在你的 csproj 文件中添加以下配置（通常在 PropertyGroup 内）：

<PropertyGroup>
    <!-- ... 其他配置 ... -->
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

3.配置 Swagger UI

在 Startup.cs 文件的 Configure 方法中，启用 Swagger UI 中间件：

public void Configure(IApplicationBuilder app)
{
    // ... 其他中间件配置 ...

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

    // ... 其他中间件配置 ...
}

4.运行和测试

 现在，当你运行你的 ASP.NET Core 应用时，你应该可以在 /swagger 路径下看到 Swagger UI。你可以在这里浏览你的 API，查看每个端点的文档，甚至测试它们。