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方法：
