如何在Net6.0裡配置多版本支援並支援註釋說明的Swagger

可均可可發表於2023-02-23
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有了新版本，我們也不用怕了，只要按我的設定，就可以靈活應付。不負蒼天，繼續努力。

相關文章