一、前言
现在已经进入了微服务的开发时代了,在这个时代,如果有人问你什么是微服务,你说不知道,就有点太丢人了,别人会有异样的眼光看你,俗话说:唾液淹死人。没办法,我们只能去学习新的东西。一提到微服务,有一个绕不过的话题就是作为微服务的载体,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有了新版本,我们也不用怕了,只要按我的设置,就可以灵活应付。不负苍天,继续努力。