Asp.Net Core学习笔记——Swagger实现API文档功能
1.简介
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。它提供了一个Web UI，通过这UI，你不仅可以浏览有关API的信息，而且可以在线测试API。
2.创建ASP.NET Core Web API项目
在ConfigureServices添加Swagger中间件。
public void ConfigureServices(IServiceCollection services) { services.AddControllers(); //注册Swagger生成器，定义一个和多个Swagger 文档 services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Version = "v1.0.0", Title = "我的接口" });
}); }
选择项目右键属性
先引入NuGet包:Microsoft.Extensions.PlatformAbstractions。
如果对接口做了xml注释，要在Startup添加如下代码：
//如果对接口做了xml注释，要在Startup添加如下代码
var basePath = PlatformServices.Default.Application.ApplicationBasePath;
var xmlPath = Path.Combine(basePath, "MySwaggerDemo.xml");
c.IncludeXmlComments(xmlPath);
public void ConfigureServices(IServiceCollection services) { services.AddControllers(); //注册Swagger生成器，定义一个和多个Swagger 文档 services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Version = "v1.0.0", Title = "我的接口" }); //如果对接口做了xml注释，要在Startup添加如下代码 var basePath = PlatformServices.Default.Application.ApplicationBasePath; var xmlPath = Path.Combine(basePath, "MySwaggerDemo.xml"); c.IncludeXmlComments(xmlPath); }); }
在Configure配置Swagger中间件
public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } //启用中间件服务生成Swagger作为JSON终结点 app.UseSwagger(); //启用中间件服务对swagger-ui，指定Swagger JSON终结点 app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); }); app.UseHttpsRedirection(); app.UseRouting(); app.UseAuthorization(); app.UseEndpoints(endpoints => { endpoints.MapControllers(); }); }
添加一个控制器
/// <summary> /// User控制器 /// </summary> [Route("api/[controller]")] [ApiController] public class UserController : ControllerBase { /// <summary> /// 根据Id获取信息 /// </summary> /// <param name="id">Id</param> /// <returns></returns> [HttpPost("GetInfoById")] public string GetName(string id = "") { return "张三"; } }
在launchSettings.json中修改launchUrl数值量，从而改变默认启动页。
运行项目
3.支持多个 Api版本
通过 NuGet 安装此软件包：Microsoft.AspNetCore.Mvc.Versioning。
在Startup.cs类的ConfigureServices()方法中配置服务：
services.AddApiVersioning()；
public void ConfigureServices(IServiceCollection services) { services.AddMvc(); services.AddApiVersioning(); }
在Startup.cs类的Configure方法加入app.UseApiVersioning()启用多个API版本。
使用MapToApiVersion定义特定Action API版本号(访问路径：http://localhost:5000/api/[controller]?api-version=1.0)。
/// <summary> /// User控制器 /// </summary> [ApiVersion("1.0")] [Route("api/[controller]")] [ApiController] public class UserController : ControllerBase { /// <summary> /// 根据Id获取信息 /// </summary> /// <param name="id">Id</param> /// <returns></returns> [MapToApiVersion("1.0")] [HttpPost("GetInfoById")] public string GetName(string id = "") { return "张三"; } }
在Startup.cs类的Configure方法中将services.AddApiVersioning()：
services.AddApiVersioning(options => options.AssumeDefaultVersionWhenUnspecified = true);
这样写的目的是让ASP.NET Core 把默认的控制器和Action设置版本1.0。
其实我们也可以改成这样的方式： http://localhost:5000/api/v1/values访问：
/// <summary> /// User控制器 /// </summary> [ApiVersion("1.0")] [Route("api/v{version:apiVersion}/[controller]")] [ApiController] public class UserController : ControllerBase { /// <summary> /// 根据Id获取信息 /// </summary> /// <param name="id">Id</param> /// <returns></returns> [MapToApiVersion("1.0")] [HttpPost("GetInfoById")] public string GetName(string id = "") { return "张三"; } }
服务配置为从特定的媒体类型：
services.AddApiVersioning(options => { options.ApiVersionReader = new MediaTypeApiVersionReader(); options.AssumeDefaultVersionWhenUnspecified = true; options.ApiVersionSelector = new CurrentImplementationApiVersionSelector(options); });
发送HTTP请求时，在请求头中content-type指定API版本号，若不指定版本默认使用最新版本：
