经验首页 前端设计 程序设计 Java相关 移动开发 数据库/运维 软件/图像 大数据/云计算 其他经验
当前位置:技术经验 » 程序设计 » ASP.net » 查看文章
如何在Net6.0里配置多版本支持并支持注释说明的Swagger
来源:cnblogs  作者:可均可可  时间:2023/2/24 9:08:31  对本文有异议

一、前言
    现在已经进入了微服务的开发时代了,在这个时代,如果有人问你什么是微服务,你说不知道,就有点太丢人了,别人会有异样的眼光看你,俗话说:唾液淹死人。没办法,我们只能去学习新的东西。一提到微服务,有一个绕不过的话题就是作为微服务的载体,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. 1 /// <summary>
  2. 2 /// 该类型定义了 WebAPI 版本的信息。
  3. 3 /// </summary>
  4. 4 public static class ApiVersionInfo
  5. 5 {
  6. 6 /// <summary>
  7. 7 /// 初始化默认值。
  8. 8 /// </summary>
  9. 9 static ApiVersionInfo()
  10. 10 {
  11. 11 V1 = string.Empty;
  12. 12 V2 = string.Empty;
  13. 13 V3 = string.Empty;
  14. 14 V4 = string.Empty;
  15. 15 }
  16. 16
  17. 17 /// <summary>
  18. 18 /// 获取或者设置 V1 版本。
  19. 19 /// </summary>
  20. 20 public static string V1;
  21. 21
  22. 22 /// <summary>
  23. 23 /// 获取或者设置 V2 版本。
  24. 24 /// </summary>
  25. 25 public static string V2;
  26. 26
  27. 27 /// <summary>
  28. 28 /// 获取或者设置 V3 版本。
  29. 29 /// </summary>
  30. 30 public static string V3;
  31. 31
  32. 32 /// <summary>
  33. 33 /// 获取或者设置 V4 版本。
  34. 34 /// </summary>
  35. 35 public static string V4;
  36. 36 }


    2、我们在 Program 里面配置 Swagger ,具体分为两个部分。

  1. 1 using PatrickLiu.Net6.WebApiDetails.Extensions;
  2. 2 using System.Reflection;
  3. 3
  4. 4 var builder = WebApplication.CreateBuilder(args);
  5. 5
  6. 6 // Add services to the container.
  7. 7
  8. 8 builder.Services.AddControllers();
  9. 9 // Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
  10. 10 builder.Services.AddEndpointsApiExplorer();
  11. 11
  12. 12 #region 自定义配置Swagger
  13. 13
  14. 14 builder.Services.AddSwaggerGen(c =>
  15. 15 {
  16. 16 foreach (FieldInfo field in typeof(ApiVersionInfo).GetFields())
  17. 17 {
  18. 18 c.SwaggerDoc(field.Name, new Microsoft.OpenApi.Models.OpenApiInfo()
  19. 19 {
  20. 20 Title = $"{field.Name}:这里是 PatrickLiu 教育",
  21. 21 Version = field.Name,
  22. 22 Description = $"当前的 ASP.Net Core Web API {field.Name} 版本"
  23. 23 });
  24. 24 }
  25. 25
  26. 26 #region 增加api读取注释
  27. 27
  28. 28 //获取应用程序所在目录(绝对不受工作目录影响,建议采用此方法获取路径)
  29. 29 string? basePath = Path.GetDirectoryName(typeof(Program).Assembly.Location);
  30. 30
  31. 31 if (!string.IsNullOrEmpty(basePath) && !string.IsNullOrWhiteSpace(basePath))
  32. 32 {
  33. 33 string xmlPath = Path.Combine(basePath, "PatrickLiu.Net6.WebApiDetails.xml");
  34. 34 c.IncludeXmlComments(xmlPath);
  35. 35 }
  36. 36
  37. 37 #endregion
  38. 38 });
  39. 39
  40. 40 #endregion
  41. 41
  42. 42 #region 日志扩展
  43. 43
  44. 44 //builder.Logging.AddLog4Net("Config/log4net.config");
  45. 45
  46. 46 builder.Services.AddLogging(builder =>
  47. 47 {
  48. 48 builder.AddLog4Net("Config/log4net.config");
  49. 49 });
  50. 50
  51. 51 #endregion
  52. 52
  53. 53 var app = builder.Build();
  54. 54
  55. 55 #region Swagger 具体的配置
  56. 56
  57. 57 app.UseSwagger();
  58. 58 app.UseSwaggerUI(c =>
  59. 59 {
  60. 60 foreach (FieldInfo field in typeof(ApiVersionInfo).GetFields())
  61. 61 {
  62. 62 c.SwaggerEndpoint($"/swagger/{field.Name}/swagger.json", $"{field.Name}");
  63. 63 }
  64. 64 });
  65. 65
  66. 66 #endregion
  67. 67
  68. 68 app.UseAuthorization();
  69. 69
  70. 70 app.MapControllers();
  71. 71
  72. 72 app.Run();


    3、我们建立我们自己的 APIController ,为每个 Controller 增加 [ApiExplorerSettings(GroupName = nameof(ApiVersionInfo.版本号)) ],我就创建了2个Controller。

  1. /// <summary>
  2. /// 订单的服务控制器。
  3. /// </summary>
  4. [Route("api/[controller]/[action]")]
  5. [ApiController]
  6. [ApiExplorerSettings(GroupName =nameof(ApiVersionInfo.V1))]
  7. public class OrdersController : ControllerBase
  8. {
  9. /// <summary>
  10. /// 获取数据列表。
  11. /// </summary>
  12. /// <returns></returns>
  13. [HttpGet]
  14. [Route("GetAll")]
  15. public IEnumerable<string> Get()
  16. {
  17. return new string[] { "value1", "value2" };
  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. /// <summary>
  30. /// 增加数据。
  31. /// </summary>
  32. /// <param name="value">参数</param>
  33. [HttpPost]
  34. public void Post([FromBody] string value)
  35. {
  36. }
  37. /// <summary>
  38. /// 修改数据。
  39. /// </summary>
  40. /// <param name="id">查询主键。</param>
  41. /// <param name="value">要修改的值。</param>
  42. [HttpPut("{id}")]
  43. public void Put(int id, [FromBody] string value)
  44. {
  45. }
  46. /// <summary>
  47. /// 删除数据。
  48. /// </summary>
  49. /// <param name="id">要删除的主键。</param>
  50. [HttpDelete("{id}")]
  51. public void Delete(int id)
  52. {
  53. }
  54. }
  1. 1 /// <summary>
  2. 2 ///
  3. 3 /// </summary>
  4. 4 [Route("v2/api/[controller]")]
  5. 5 [ApiController]
  6. 6 [ApiExplorerSettings(GroupName = nameof(ApiVersionInfo.V2))]
  7. 7 public class OrdersV2Controller : ControllerBase
  8. 8 {
  9. 9 /// <summary>
  10. 10 /// 获取数据列表。
  11. 11 /// </summary>
  12. 12 /// <returns></returns>
  13. 13 [HttpGet]
  14. 14 public IEnumerable<string> Get()
  15. 15 {
  16. 16 return new string[] { "value1", "value2" };
  17. 17 }
  18. 18
  19. 19 /// <summary>
  20. 20 /// 获取主键所对应的数据。
  21. 21 /// </summary>
  22. 22 /// <param name="id">查询的主键。</param>
  23. 23 /// <returns></returns>
  24. 24 [HttpGet("{id}")]
  25. 25 public string Get(int id)
  26. 26 {
  27. 27 return "value";
  28. 28 }
  29. 29
  30. 30 /// <summary>
  31. 31 /// 增加数据。
  32. 32 /// </summary>
  33. 33 /// <param name="value">参数</param>
  34. 34 [HttpPost]
  35. 35 public void Post([FromBody] string value)
  36. 36 {
  37. 37 }
  38. 38
  39. 39 /// <summary>
  40. 40 /// 修改数据。
  41. 41 /// </summary>
  42. 42 /// <param name="id">查询主键。</param>
  43. 43 /// <param name="value">要修改的值。</param>
  44. 44 [HttpPut("{id}")]
  45. 45 public void Put(int id, [FromBody] string value)
  46. 46 {
  47. 47 }
  48. 48
  49. 49 /// <summary>
  50. 50 /// 删除数据。
  51. 51 /// </summary>
  52. 52 /// <param name="id">要删除的主键。</param>
  53. 53 [HttpDelete("{id}")]
  54. 54 public void Delete(int id)
  55. 55 {
  56. 56 }
  57. 57
  58. 58 /// <summary>
  59. 59 /// 增加一个人。
  60. 60 /// </summary>
  61. 61 /// <param name="person">要增加的人</param>
  62. 62 /// <param name="id">主键值。</param>
  63. 63 /// <param name="name">姓名。</param>
  64. 64 /// <param name="sex">性别</param>
  65. 65 /// <param name="address">地址。</param>
  66. 66 [HttpPost]
  67. 67 [Route("PutData")]
  68. 68 public void PutData(SinglePerson person,int id,string name,bool sex,string address)
  69. 69 {
  70. 70
  71. 71 }
  72. 72 }


    4、运行起来,看看效果吧。

      

 


三、结束语
    当我们的WebAPI有了新版本,我们也不用怕了,只要按我的设置,就可以灵活应付。不负苍天,继续努力。

原文链接:https://www.cnblogs.com/PatrickLiu/p/17147638.html

 友情链接:直通硅谷  点职佳  北美留学生论坛

本站QQ群:前端 618073944 | Java 606181507 | Python 626812652 | C/C++ 612253063 | 微信 634508462 | 苹果 692586424 | C#/.net 182808419 | PHP 305140648 | 运维 608723728

W3xue 的所有内容仅供测试,对任何法律问题及风险不承担任何责任。通过使用本站内容随之而来的风险与本站无关。
关于我们  |  意见建议  |  捐助我们  |  报错有奖  |  广告合作、友情链接(目前9元/月)请联系QQ:27243702 沸活量
皖ICP备17017327号-2 皖公网安备34020702000426号