Swagger是最流行的API开发工具，它遵循了OpenAPI规范，可以根据API接口自动生成在线文档，这样就可以解决文档更新不及时的问题。它可以贯穿于整个API生态，比如API的设计、编写API文档等。而且Swagger还是一种通用的、与具体编程语言无关的API描述规范。
有关更多Swagger的介绍，可以参考Swagger官网，官网地址：https://swagger.io/
1、添加Swagger
直接在NuGet里面搜索Swashbuckle.AspNetCore包进行安装：
2、添加服务
在Startup类的ConfigureServices方法里面注入服务：
public void ConfigureServices(IServiceCollection services)
{
// 添加Swagger
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "API Demo", Version = "v1" });
});
services.AddControllers();
}
3、添加中间件
在Startup类的Configure方法里面添加Swagger有关的中间件：
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
// 添加Swagger有关中间件
app.UseSwagger();
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "API Demo v1");
});
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}
4、添加控制器
新建一个控制器，里面包括基础的增删改查方法：
using Microsoft.AspNetCore.Mvc;
namespace SwaggerDemo.Controllers
{
[Route("api/student")]
[ApiController]
public class StudentController : ControllerBase
{
[HttpGet]
public string Get()
{
return "Tom";
}
[HttpPost]
public void Post()
{
}
[HttpPut]
public void Put()
{
}
[HttpDelete]
public void Delete()
{
}
}
}
运行程序，修改一下url地址：
http://localhost:5000/swagger/index.html
这样就可以看到接口了。但这样还不是我们最终想要的结果，我们想知道每个方法的注释和方法参数的注释，这就需要对接口做XML注释了。
首先安装Microsoft.Extensions.PlatformAbstractions包：
然后修改ConfigureServices方法，增加下面的方法：
public void ConfigureServices(IServiceCollection services)
{
#region 添加Swagger
services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1",new OpenApiInfo { Title = "My API", Version = "v1" });
// 获取xml文件名
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
// 获取xml文件路径
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
// 添加控制器层注释，true表示显示控制器注释
options.IncludeXmlComments(xmlPath, true);
});
#endregion
services.AddControllers();
}
然后给新建的接口添加注释：
using Microsoft.AspNetCore.Mvc;
namespace SwaggerDemo.Controllers
{
/// <summary>
/// 学生控制器
/// </summary>
[Route("api/student")]
[ApiController]
public class StudentController : ControllerBase
{
/// <summary>
/// 获取所有学生
/// </summary>
/// <returns></returns>
[HttpGet]
public string Get()
{
return "Tom";
}
/// <summary>
/// 新增学生
/// </summary>
[HttpPost]
public void Post()
{
}
/// <summary>
/// 修改学生信息
/// </summary>
[HttpPut]
public void Put()
{
}
/// <summary>
/// 删除学生信息
/// </summary>
[HttpDelete]
public void Delete()
{
}
}
}
项目右键，选择属性，勾选“XML文档文件”，如下图所示：
在运行程序：
Swagger除了可以显示接口注释以外，还可以进行调试，以前调试都是使用Postman，我们也可以直接使用Swagger进行调试
这时候是不能输入的，只能查看，点击右上角的“Try it out”：
这样就完成了GET方法的调试。这是无参数方法的调试，如果有参数的方法怎么调试呢？我们以POT方法为例。我们点开POST方法：
