如何在Net6.0里配置多版本支持并支持注释说明的Swagger
一、前言
现在已经进入了微服务的开发时代了，在这个时代，如果有人问你什么是微服务，你说不知道，就有点太丢人了，别人会有异样的眼光看你，俗话说：唾液淹死人。没办法，我们只能去学习新的东西。一提到微服务，有一个绕不过的话题就是作为微服务的载体，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有了新版本，我们也不用怕了，只要按我的设置，就可以灵活应付。不负苍天，继续努力。
天下国家,可均也；爵禄,可辞也；白刃,可蹈也；中庸不可能也
转 https://www.cnblogs.com/PatrickLiu/p/17147638.html
浙公网安备 33010602011771号