周末，寫點簡單的水一下。
新版本的vs創(chuàng)建項目的時候可以選擇自帶一個swagger。然而這只是基本的swagger功能。
幾個接口無所謂啦，隨著接口越來越多，就這么丟給你，一時間也會懵逼，所以這篇文章要做的有兩個功能。
- 給swagger文檔添加注釋
- 給swagger添加切換“版本”的功能(也可以理解為：讓不同功能模塊的接口顯示在一個頁面，不然幾十上百的接口放一起找也不好找呀~)
右鍵項目>屬性>生成>輸出>XML文檔文件路徑，添加輸出的路徑，我一般會設(shè)置在程序集下的根路徑，例如這樣：
文件命名什么的隨意，一般跟項目有關(guān)例如：FastEasy.Readme.xml。
然后去swagger相關(guān)的Module模塊中去添加一些配置。我這個文章相關(guān)的項目一開始的時候就將這些注入配置單獨搞成獨立的一個模塊，所以你只是看到這個文章，那默認(rèn)就在Programs里面找AddSwaggerGen就好。
Services.AddSwaggerGen(s => { //多版本 typeof(SwaggerVersion).GetEnumNames().ToList().ForEach(v => { s.SwaggerDoc(v, new Microsoft.OpenApi.Models.OpenApiInfo { Version = v, Description = $"{v} API", Title = v, }); //添加注釋 var basePath=AppDomain.CurrentDomain.BaseDirectory; var xmlPath = Path.Combine(basePath, "FastEasy.Readme.xml"); s.IncludeXmlComments(xmlPath,true); }); });
如果不需要切換版本，那就關(guān)注添加注釋下面三行代碼就好，獲取注釋文檔的路徑，然后添加到swagger中。
接下來就是多版本切換，上面的代碼已經(jīng)是了，需要在意的地方是typeof里的SwaggerVersion。這是創(chuàng)建的一個枚舉，然后在枚舉中按需添加不同的版本切換，例如
public enum SwaggerVersion { FastEasy = 1, OpenAPI = 2 }
如果要使用多版本，中間件管道里也要改一下
app.UseSwagger(); app.UseSwaggerUI(s => { typeof(SwaggerVersion).GetEnumNames().ToList().ForEach(v => { s.SwaggerEndpoint($"swagger/{v}/swagger.json", $"{v}"); s.RoutePrefix = string.Empty; }); });
到這里就已經(jīng)完成90%了。最后一步就是給不同的方法或者控制器添加[ApiExplorerSettings(GroupName = "OpenAPI")]
[HttpGet("MUL")] [ApiExplorerSettings(GroupName = "OpenAPI")] public int MUL(int i, int j) { return test.MUL(i, j); }
原本是加減乘除4個接口，現(xiàn)在就是FastEasy下兩個，OpenAPI下兩個(只是測試，跟名稱毫無關(guān)系)
現(xiàn)在完成了99%了。如果像我這種小公司，沒有版本的區(qū)別，無非就是為了看著方便，因為功能模塊去區(qū)分開來。就像現(xiàn)在，查看文檔的時候可以根據(jù)分類找到相對應(yīng)的接口，不至于一眼亂糟糟的。
但是實際上并未完成版本控制，因為你會發(fā)現(xiàn)，他們的請求路徑是差不多的。如果要完成真正的版本控制，有兩種方法，第一種簡單，路由上寫死了：/v1/xxxx /v2/xxxxx……
第二種就是自定義路由特性：添加一個特性配置的類:SwaagerRouteAttribute。我直接貼代碼了，很簡單的幾行，代碼的注釋足以解釋清楚了
public class SwaagerRouteAttribute : RouteAttribute, IApiDescriptionGroupNameProvider { /// <summary> /// 默認(rèn)的路由配置 /// </summary> /// <param name="actionName"></param> public SwaagerRouteAttribute(string actionName) : base(actionName) { } /// <summary> /// 分組名稱,控制不同版本:等同于配置ApiExplorerSettings(GroupName ="FastEasy") /// </summary> public string? GroupName { get; set; } /// <summary> /// 自定義的路由配置 /// </summary> /// <param name="version"></param> /// <param name="actionName"></param> public SwaagerRouteAttribute(SwaggerVersion version, string actionName = "[action]") : base($"/{version.ToString()}/[controller]/{actionName}") { GroupName = version.ToString(); } }
現(xiàn)在！用自己封裝的路由屬性添加到方法上面(截圖看的全)
此時才算完成真的版本控制效果：
啊掰掰~
浙公網(wǎng)安備 33010602011771號