为 .Net Core Web API 项目添加 Swagger 支持

在前、后端分离的项目开发中，清晰、完整、且与程序同步的 Web API 文档是非常重要的。在 .NET Core 项目中，可以通过在项目中添加 Swagger 来方便的制作 Web API 文档。

本文演示环境基于: .NET Core SDK 3.1

安装 Swagger

在 .NET Core 项目中，可以使用以下命令安装 Swagger 支持:

1	dotnet add TodoApi.csproj package Swashbuckle.AspNetCore -v 5.3.3

启用 Swagger

安装好 Swagger 之后，要启用 Swagger, 需要修改项目的 Startup.cs 文件。

在 ConfigureServices 方法中添加 Swagger 的生成器，代码如下:

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

该语句声明了需要生成的 API 及 API 文档的基本信息

在 Configure 方法中启用 Swagger 及 SwaggerUI, 代码如下:

app.UseSwagger();

 app.UseSwaggerUI(c =>
 {
     c.SwaggerEndpoint("/swagger/v1/swagger.json", "Web API V1");
 });

这些语句让 Swagger 产生相关的 API 文档并建立一个访问点。

接下来就可以运行项目，并访问:

1	https://localhost:5001/swagger/

就可以看到已经已经生成了项目中已经有的 API 文档。 关键还可以直接测试这些 API 方法, 在一定程度上省去了安装启动测试工具（如：Postman)的麻烦

为API添加更多的说明

在完成上面的步骤后， Swagger 已经为项目生成了一些信息，并提供了要给可以直接测试 API 的页面。接下来，我们试试为每个 API 再增加一些说明信息，以便于前端开发人员阅读。

在项目配置文件(.csproj文件)的 “PropertyGroup” 组中添加如下设置:

1	<GenerateDocumentationFile>true</GenerateDocumentationFile>

在 Startup.cs 文件的 “Configuration” 方法的 AddSwaggerGen 调用中添加如下行:

1
2
3

var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);

在 Startup.cs 中需要引入以下新的包:

1 2	using System.Reflection; using System.IO;

添加完之后，完整的 ConfigureServices 方法如下(供参考):

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

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

        var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
        var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
        c.IncludeXmlComments(xmlPath);
    });

}

接下来就可以在需要添加信息的方法中编辑接口信息了。

使用 “
“ 添加一个接口的描述信息，比如下面的代码为 “WeatherForecast” 的 HttpGet 请求添加信息:

/// <summary>
/// 获取完整的天气信息
/// </summary>
[HttpGet]
public IEnumerable<WeatherForecast> Get()
{
    var rng = new Random();
    return Enumerable.Range(1, 5).Select(index => new WeatherForecast
    {
        Date = DateTime.Now.AddDays(index),
        TemperatureC = rng.Next(-20, 55),
        Summary = Summaries[rng.Next(Summaries.Length)]
    })
    .ToArray();
}

这样就可以在 Swagger 产生的 API 文档中看到对该 API 功能的描述。

使用 ““ 可以提供更详细的使用描述，包括算法说明、参数说明、特殊值等等。如:

/// <summary>
/// 获取完整的天气信息
/// </summary>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item1",
///        "isComplete": true
///     }
///
/// </remarks>