为 .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 文件。

  1. 在 ConfigureServices 方法中添加 Swagger 的生成器,代码如下:
1
2
3
4
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "Web API", Version = "v1" });
});

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

  1. 在 Configure 方法中启用 Swagger 及 SwaggerUI, 代码如下:
1
2
3
4
5
6
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 再增加一些说明信息,以便于前端开发人员阅读。

  1. 在项目配置文件(.csproj文件)的 “PropertyGroup” 组中添加如下设置:
1
<GenerateDocumentationFile>true</GenerateDocumentationFile>
  1. 在 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 方法如下(供参考):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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);
});

}

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

  1. 使用 ““ 添加一个接口的描述信息,比如下面的代码为 “WeatherForecast” 的 HttpGet 请求添加信息:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/// <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 功能的描述。

  1. 使用 ““ 可以提供更详细的使用描述,包括算法说明、参数说明、特殊值等等。 如:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
/// <summary>
/// 获取完整的天气信息
/// </summary>
/// <remarks>
/// Sample request:
///
/// POST /Todo
/// {
/// "id": 1,
/// "name": "Item1",
/// "isComplete": true
/// }
///
/// </remarks>

本文标题:为 .Net Core Web API 项目添加 Swagger 支持

文章作者:梅老师

发布时间:2020年06月14日 - 16:06

最后更新:2020年06月14日 - 16:06

原始链接:https://www.mls-tech.info/dotnet/dotnet-core-use-swagger-doc/

许可协议: 署名-非商业性使用-禁止演绎 4.0 国际 转载请保留原文链接及作者。