一、前言
现在已经进入了微服务的开发时代了，在这个时代，如果有人问你什么是微服务，你说不知道，就有点太丢人了，别人会有异样的眼光看你，俗话说：唾液淹死人。没办法，我们只能去学习新的东西。一提到微服务，有一个绕不过的话题就是作为微服务的载体，WebAPI是离不开的。但是我们今天不讲WebAPI是什么，如何开发API，以及如何开发Restfull风格的API，我们聊另外一个话题，如何配置Swagger，让其支持多版本，并且支持参数、方法的注释说明。
为什么我们会说这呢，因为，我们要开发API，就会涉及到别人如何使用你的API，相应的使用文档就少不了，当时当我们有了Swagger，就不一样了。Swagger会为我们提供这个文档的功能。
我们今天开发的环境是：
操作系统：Windows 10 Professional
开发工具：Visual Studio 2022
开发语言：C#
开发平台：Asp.Net Core Web API 6.0。
平台类型：跨平台。
二、我们开始配置Swagger，让其支持多版本和注释。
在我们开始配置之前，先有一个直观的感受，我直接上一个截图。
先来第一张截图，概况展示：
再来一张，接口内部详情的：
1、我们先设置一个版本信息的工具类，这个工具类可以放在单独的类库项目中，也可以放在 WebAPI 当前的项目中。
1 /// <summary> 2 /// 该类型定义了 WebAPI 版本的信息。 3 /// </summary> 4 public static class ApiVersionInfo 5 { 6 /// <summary> 7 /// 初始化默认值。 8 /// </summary> 9 static ApiVersionInfo() 10 { 11 V1 = string.Empty; 12 V2 = string.Empty; 13 V3 = string.Empty; 14 V4 = string.Empty; 15 } 16 17 /// <summary> 18 /// 获取或者设置 V1 版本。 19 /// </summary> 20 public static string V1; 21 22 /// <summary> 23 /// 获取或者设置 V2 版本。 24 /// </summary> 25 public static string V2; 26 27 /// <summary> 28 /// 获取或者设置 V3 版本。 29 /// </summary> 30 public static string V3; 31 32 /// <summary> 33 /// 获取或者设置 V4 版本。 34 /// </summary> 35 public static string V4; 36 }
2、我们在 Program 里面配置 Swagger ，具体分为两个部分。
1 using PatrickLiu.Net6.WebApiDetails.Extensions; 2 using System.Reflection; 3 4 var builder = WebApplication.CreateBuilder(args); 5 6 // Add services to the container. 7 8 builder.Services.AddControllers(); 9 // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle 10 builder.Services.AddEndpointsApiExplorer(); 11 12 #region 自定义配置Swagger 13 14 builder.Services.AddSwaggerGen(c => 15 { 16 foreach (FieldInfo field in typeof(ApiVersionInfo).GetFields()) 17 { 18 c.SwaggerDoc(field.Name, new Microsoft.OpenApi.Models.OpenApiInfo() 19 { 20 Title = $"{field.Name}:这里是 PatrickLiu 教育", 21 Version = field.Name, 22 Description = $"当前的 ASP.Net Core Web API {field.Name} 版本" 23 }); 24 } 25 26 #region 增加api读取注释 27 28 //获取应用程序所在目录（绝对不受工作目录影响，建议采用此方法获取路径） 29 string? basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location); 30 31 if (!string.IsNullOrEmpty(basePath) && !string.IsNullOrWhiteSpace(basePath)) 32 { 33 string xmlPath = Path.Combine(basePath, "PatrickLiu.Net6.WebApiDetails.xml"); 34 c.IncludeXmlComments(xmlPath); 35 } 36 37 #endregion 38 }); 39 40 #endregion 41 42 #region 日志扩展 43 44 //builder.Logging.AddLog4Net("Config/log4net.config"); 45 46 builder.Services.AddLogging(builder => 47 { 48 builder.AddLog4Net("Config/log4net.config"); 49 }); 50 51 #endregion 52 53 var app = builder.Build(); 54 55 #region Swagger 具体的配置 56 57 app.UseSwagger(); 58 app.UseSwaggerUI(c => 59 { 60 foreach (FieldInfo field in typeof(ApiVersionInfo).GetFields()) 61 { 62 c.SwaggerEndpoint($"/swagger/{field.Name}/swagger.json", $"{field.Name}"); 63 } 64 }); 65 66 #endregion 67 68 app.UseAuthorization(); 69 70 app.MapControllers(); 71 72 app.Run();
3、我们建立我们自己的 APIController ，为每个 Controller 增加 [ApiExplorerSettings(GroupName = nameof(ApiVersionInfo.版本号)) ]，我就创建了2个Controller。
/// <summary> /// 订单的服务控制器。 /// </summary> [Route("api/[controller]/[action]")] [ApiController] [ApiExplorerSettings(GroupName =nameof(ApiVersionInfo.V1))] public class OrdersController : ControllerBase { /// <summary> /// 获取数据列表。 /// </summary> /// <returns></returns> [HttpGet] [Route("GetAll")] public IEnumerable<string> Get() { return new string[] { "value1", "value2" }; } /// <summary> /// 获取主键所对应的数据。 /// </summary> /// <param name="id">查询的主键。</param> /// <returns></returns> [HttpGet("{id}")] public string Get(int id) { return "value"; } /// <summary> /// 增加数据。 /// </summary> /// <param name="value">参数</param> [HttpPost] public void Post([FromBody] string value) { } /// <summary> /// 修改数据。 /// </summary> /// <param name="id">查询主键。</param> /// <param name="value">要修改的值。</param> [HttpPut("{id}")] public void Put(int id, [FromBody] string value) { } /// <summary> /// 删除数据。 /// </summary> /// <param name="id">要删除的主键。</param> [HttpDelete("{id}")] public void Delete(int id) { } }
1 /// <summary> 2 /// 3 /// </summary> 4 [Route("v2/api/[controller]")] 5 [ApiController] 6 [ApiExplorerSettings(GroupName = nameof(ApiVersionInfo.V2))] 7 public class OrdersV2Controller : ControllerBase 8 { 9 /// <summary> 10 /// 获取数据列表。 11 /// </summary> 12 /// <returns></returns> 13 [HttpGet] 14 public IEnumerable<string> Get() 15 { 16 return new string[] { "value1", "value2" }; 17 } 18 19 /// <summary> 20 /// 获取主键所对应的数据。 21 /// </summary> 22 /// <param name="id">查询的主键。</param> 23 /// <returns></returns> 24 [HttpGet("{id}")] 25 public string Get(int id) 26 { 27 return "value"; 28 } 29 30 /// <summary> 31 /// 增加数据。 32 /// </summary> 33 /// <param name="value">参数</param> 34 [HttpPost] 35 public void Post([FromBody] string value) 36 { 37 } 38 39 /// <summary> 40 /// 修改数据。 41 /// </summary> 42 /// <param name="id">查询主键。</param> 43 /// <param name="value">要修改的值。</param> 44 [HttpPut("{id}")] 45 public void Put(int id, [FromBody] string value) 46 { 47 } 48 49 /// <summary> 50 /// 删除数据。 51 /// </summary> 52 /// <param name="id">要删除的主键。</param> 53 [HttpDelete("{id}")] 54 public void Delete(int id) 55 { 56 } 57 58 /// <summary> 59 /// 增加一个人。 60 /// </summary> 61 /// <param name="person">要增加的人</param> 62 /// <param name="id">主键值。</param> 63 /// <param name="name">姓名。</param> 64 /// <param name="sex">性别</param> 65 /// <param name="address">地址。</param> 66 [HttpPost] 67 [Route("PutData")] 68 public void PutData(SinglePerson person,int id,string name,bool sex,string address) 69 { 70 71 } 72 }
4、运行起来，看看效果吧。
三、结束语
当我们的WebAPI有了新版本，我们也不用怕了，只要按我的设置，就可以灵活应付。不负苍天，继续努力。