Swagger简介
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务。Swagger遵循OpenAPI规范（原Swagger规范），允许开发人员设计、构建、记录和使用RESTful Web服务。Swagger工具集包括Swagger Editor、Swagger UI和Swagger Codegen，分别用于API文档的编写、API文档的展示和客户端代码的自动生成。
集成Swagger到Asp.Net Core
在Asp.Net Core项目中集成Swagger，主要分为以下几个步骤：
- 安装Swagger NuGet包在项目中通过NuGet包管理器安装Swashbuckle.AspNetCore包。可以使用NuGet Package Manager Console执行以下命令：
Install-Package Swashbuckle.AspNetCore或者使用Visual Studio的NuGet包管理器界面进行安装。
- 配置Swagger服务在Startup.cs文件的ConfigureServices方法中配置Swagger服务。
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
// 添加Swagger生成器，定义一个和多个Swagger文档
services.AddSwaggerGen(c =>
{
c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
// 为Swagger UI设置XML注释路径
var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);
});
}注意：为了让Swagger显示控制器和方法的注释，你需要在项目属性中启用XML文档生成，并确保生成的XML文件路径正确。
- 启用Swagger中间件在Startup.cs文件的Configure方法中启用Swagger中间件，以便在应用程序中提供Swagger UI。
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseHttpsRedirection();
app.UseRouting();
app.UseAuthorization();
// 启用中间件服务生成Swagger作为JSON终结点
app.UseSwagger();
// 启用中间件服务对swagger-ui，指定Swagger JSON终结点
app.UseSwaggerUI(c =>
{
c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
}- 为控制器和动作添加注释在你的控制器和动作方法上使用XML注释来描述你的API。例如：
///
/// 学生控制器
///
[ApiController]
[Route("[controller]")]
public class StudentsController : ControllerBase
{
///
/// 获取所有学生信息
///
/// 学生列表
[HttpGet]
public IActionResult GetStudents()
{
// 实现逻辑
return Ok(new List { "Tom", "Jerry" });
}
// 其他动作方法...
} 访问Swagger UI
启动你的Asp.Net Core应用程序，并在浏览器中访问http://localhost:
结论
通过集成Swagger到Asp.Net Core项目中，你可以自动生成清晰、易读的API文档，并提供交互式界面进行测试，极大地提升了开发效率和团队协作效率。
