在换了新工作后，我几乎没有接触到.NET Core了，但是，它是我程序语言中的母语，我怎么能忘了它呢？其实我是想等.NET 5出来的时候再来学习。在.NET 5正式发布之前还是先对之前的东西复习一下，那么就先从.NET Core 使用swagger生成接口文档开始吧。
这里先配一张图吧
我非常期待.NET 5的到来，到正式发布的时候，一定要去尝尝鲜。好了，继续我们的 .NET Core吧，我这里的环境是
.NET Core 3.1.401
Microsoft Visual Studio 16.7.2
Swashbuckle.AspNetCore 5.5.1
好了，我们来用号称宇宙第一IDE的VS创建一个简单的
WebAPI
项目
这里我没有采用
IIS Express
方式运行，而我采用的它自宿主的方式
默认情况下，在调试模式运行的时候，会自动打开默认浏览器，因为在项目有做了设置
我也可以设置我们默认打开的浏览器
在开发WebAPI的时候，没有接口文档是非常难受的，离线文档固然好，但是更新不及时，所以我们需要一个能在线实时更新的的接口文档，那么Swagger备受众多开发者的青睐，所以它成了我们的不二之选。
现在，去引入Swashbuckle.AspNetCore组件，这里有三种方式
NuGet图形化
Package Manager命令行 Install-Package Swashbuckle.AspNetCore -Version 5.5.1
.NET Core CLI 命令 dotnet add CoreDemo.csproj package --version 5.5.1 Swashbuckle.AspNetCore
NeGet方式安装
Package Manager命令行
.NET Core CLI
然后，我们创建一个
Controller
类
按照向导创建完成后，会基于API模版生成一些基础代码
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
namespace CoreDemo.Controllers
[Route("api/[controller]")]
[ApiController]
public class DemoController : ControllerBase
为了演示，先写个简单的GET请求接口
using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
namespace CoreDemo.Controllers
[Route("api/[controller]")]
[ApiController]
public class DemoController : ControllerBase
[HttpGet]
public string GetVersion()
现在就开始配置Swagger，我们需要分别在ConfigureServices和Configure两个方法种添加引用方法
public void ConfigureServices(IServiceCollection services)
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
if (env.IsDevelopment())
app.UseSwagger();
app.UseSwaggerUI(c =>
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
现在我们再次运行起来,在浏览器输入https://localhost:5001/swagger来看看效果
初版中的方法上没有注解，现在我们就需要去没个方法上加上注解，这才是接口文档该有的样子
using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
namespace CoreDemo.Controllers
[Route("api/[controller]")]
[ApiController]
public class DemoController : ControllerBase
/// <summary>
/// 查看当前版本号
/// </summary>
/// <returns></returns>
[HttpGet]
然后去属性->生成->输出中，把XML文档文件这个选项勾
再去ConfigureServices中加载我们输出的XML文档
services.AddSwaggerGen(c =>
c.SwaggerDoc("v1", new OpenApiInfo { Title = "WebAPI接口文档", Version = "v1" });
var xmlFilePath = $"{AppContext.BaseDirectory}/{Assembly.GetExecutingAssembly().GetName().Name}.xml";
c.IncludeXmlComments(xmlFilePath, true);
另外，我们再把启动路径改成我们的Swagger，这个每次运行就可以直接打开页面进行测试，而不需要手动去输一次
现在运行起来就可以看到接口的说明了
我们还可以给方法中的参数注解，这里有多种，一种就是直接是多个参数，一种是实体，如果是多个简单的参数，我们依然是直接注解的方式即可
/// <summary>
/// 打个招呼吧
/// </summary>
/// <param name="name">名字</param>
/// <returns></returns>
[HttpGet("GetName/{name}")]
public string GetName(string name)
如果是以类为参数，就需要在每个属性上加注解
/// <summary>
/// 用户信息
/// </summary>
public class UserDto
/// <summary>
/// </summary>
public string Name { get; set; }
/// <summary>
/// 年龄
/// </summary>
public int Age { get; set; }
/// <summary>
/// 提交用户信息
/// </summary>
/// <param name="user">用户信息</param>
/// <returns></returns>
[HttpPost("UserInfo")]
public string UserInfo([FromBody] UserDto user)
在我们勾选了XML文档文件之后，如果不加注释的话，就会有警告，极为不友善，像这种警告我们是可以忽略的
在上图中，我们可以看到错误代码，我们把代码添加到属性->生成->错误和警告->取消显示警告这一行中，然后重新生成一次，警告就会消失
好了，今天就先到这里，我们下回再来尝试下多版本API的Swagger文档以及添加请求头。
如果觉得《NET Core 3.x使用Swagger生成接口文档》对你有帮助，请点赞、收藏，并留下你的观点哦！
