基於 .net core 8.0 的 swagger 文檔優化分享-根據命名空間分組顯示

来源:https://www.cnblogs.com/morang/p/18284628/netcore8-swagger-group-namespace-show
-Advertisement-
Play Games

之前也分享過 Swashbuckle.AspNetCore 的使用,不過版本比較老了,本次演示用的示例版本為 .net core 8.0,從安裝使用開始,到根據命名空間分組顯示,十分的有用 ...


前言

公司項目是是微服務項目,網關是手擼的一個.net core webapi 項目,使用 refit 封裝了 20+ 服務 SDK,在網關中進行統一調用和聚合等處理,以及給前端提供 swagger 文檔
在我兩年前進公司的時候,文檔還能夠順滑的打開,在去年的時候文檔只能在本地打開,或者訪問原始的 swagger 頁面,knife4j 的頁面更是打不開一點,於是想辦法對此進行了優化

.net core 項目中使用 Swashbuckle.AspNetCore 生成 SwaggerUI

首先再記錄一下安裝及使用,之前也分享過 Swashbuckle.AspNetCore 的使用,不過版本比較老了,本次演示用的示例版本為 .net core 8.0,從安裝使用開始分享一二

安裝包

  • 新建.net core 項目
  • 添加 Swashbuckle.AspNetCore 相關包引用
  • 設置項目 xml 生成路徑,組件將根據 xml 解析介面相關信息
  <ItemGroup>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.6.2" />
    <PackageReference Include="Swashbuckle.AspNetCore.Annotations" Version="6.6.2" />
    <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="6.6.2" />
  </ItemGroup>
	<PropertyGroup>
		<DocumentationFile>bin\$(MSBuildProjectName).xml</DocumentationFile>
	</PropertyGroup>

服務配置

  • 一些基礎配置使用備忘
    • 配置文檔信息 c.SwaggerDoc
    • 配置環境 c.AddServer
    • 配置模型標識 c.CustomSchemaIds
    • 配置唯一標識 c.CustomOperationIds
    • 配置解析 xml c.IncludeXmlComments
    • 啟用數據註解 c.EnableAnnotations [SwaggerOperation]
  • 完整配置如下
//框架初始化巴拉巴拉xxx
builder.Services.AddControllers();
//配置 swagger
UseSwagger(builder.Services);

/// <summary>
/// Swagger 註入配置
/// </summary>
/// <param name="services"></param>
/// <returns></returns>
void UseSwagger(IServiceCollection services)
{
    services.AddSwaggerGen(c =>
    {
        //配置文檔信息
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Title = "swagger介面文檔測試",
            Description = "這是一個文檔",
            Version = "v1",
        });
        //配置環境
        c.AddServer(new OpenApiServer()
        {
            Url = "",
            Description = "本地"
        });
        //配置模型標識,預設type.Name,名稱一樣,不同明明空間會報錯,所以改成FullName,加上命名空間區分
        c.CustomSchemaIds(type => type.FullName);
        //配置唯一標識
        c.CustomOperationIds(apiDesc =>
        {
            var controllerAction = apiDesc.ActionDescriptor as ControllerActionDescriptor;
            return controllerAction.ControllerName + "-" + controllerAction.ActionName;
        });
        //解析站點下所有xml,一般加自己項目的引用的即可
        foreach (var file in Directory.GetFiles(AppContext.BaseDirectory, "*.xml"))
        {
            c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, file));
        }
        //啟用數據註解
        c.EnableAnnotations(true, true);
    });
}
  • 啟用 swagger

RunSwagger(app);

/// <summary>
/// 啟用swagger
/// </summary>
/// <param name="app"></param>
void RunSwagger(IApplicationBuilder app)
{
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/v1/api-docs", "V1 Docs");
    });
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapSwagger("{documentName}/api-docs");
        endpoints.MapGet("/v3/api-docs/swagger-config", async (httpContext) =>
        {
            JsonSerializerOptions jsonSerializerOptions = new JsonSerializerOptions
            {
                PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
                IgnoreNullValues = true
            };
            jsonSerializerOptions.Converters.Add(new JsonStringEnumConverter(JsonNamingPolicy.CamelCase, false));
            SwaggerUIOptions _options = new SwaggerUIOptions()
            {
                ConfigObject = new ConfigObject()
                {
                    Urls = new List<UrlDescriptor>
                        {
                            new UrlDescriptor()
                            {
                                Url="/v1/api-docs",
                                Name="V1 Docs"
                            }
                        }
                }
            };
            await httpContext.Response.WriteAsync(JsonSerializer.Serialize(_options.ConfigObject, jsonSerializerOptions));
        });
    });
}

運行

  • 運行後可以看到配置成功,swagger文檔已經生成

到這裡基礎的 swagger 配置已可以使用,更深層次的參考官方文檔使用即可,接下來才是不一樣的東西
隨著我們的項目發展,當我們的服務越來越多,介面也越來越多的時候,swagger 就從慢,到打開超時偶爾能打開,到每次都打不開(/api-docs 過大返回超時,渲染卡頓)
這個時候,或者一開始就應該對 swagger 進行分組返回了,優化 /api-docs 介面返回的數據
當然,除了這種方式,還有可以加特效標記的方式,但是幾百個服務,加不了一點

分模塊返迴文檔

一開始並沒有想到分組顯示,因為在本地運行的時候是可以打開的,只是 json 文件較大,於是做了一個優化是每次在發佈應用後,請求一個介面去將 swagger 的 json 文件生成到本地,後續訪問直接讀取,算是暫時解決了打不開的問題,這樣用了大半年,實在受不了這個速度,然後平時在看一些開源項目的時候發現是完全可以按自己的規則進行分組的,於是有了這篇文章

為了相容之前的文檔路由,所以還是在原有配置的基礎上,配置了其他模塊的介面文檔
可有兩種方式

  • 一種是在原有基礎上顯示其他分組
  • 一種是單獨的 swagger 進行顯示

優化修改

  • 先定義好需要分組顯示的模塊
//設置需要分組的api介面
var groupApis = new List<string>() { "SwaggerTest.Controllers.Test", "SwaggerTest.Controllers.Demo" };
  • UseSwagger 修改部分
  • 重點是這塊的自定義,去分組中匹配路由 c.DocInclusionPredicate 官方文檔
//配置文檔信息
c.SwaggerDoc("v1", new OpenApiInfo
{
    Title = "swagger介面文檔測試",
    Description = "這是一個文檔",
    Version = "v1",
});
//配置環境
c.AddServer(new OpenApiServer()
{
    Url = "",
    Description = "本地"
});
//模型標識配置,預設type.Name,名稱一樣,不同明明空間會報錯,所以改成FullName,加上命名空間區分
c.CustomSchemaIds(type => type.FullName);
c.CustomOperationIds(apiDesc =>
{
    var controllerAction = apiDesc.ActionDescriptor as ControllerActionDescriptor;
    return controllerAction.ControllerName + "-" + controllerAction.ActionName;
});
//載入註釋文件
foreach (var file in Directory.GetFiles(AppContext.BaseDirectory, "*.xml"))
{
    c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, file));
}
//增加模塊介面的註冊
groupApis.ForEach(s =>
{
    c.SwaggerDoc(s, new OpenApiInfo
    {
        Title = "api-" + s,
        Description = "api " + s,
        Version = "v1",
    });
});

//啟用數據註解
c.EnableAnnotations(true, true);
//自定義分組匹配
c.DocInclusionPredicate((docName, apiDes) =>
{
    if (groupApis.Contains(docName))
    {
        var displayName = apiDes.ActionDescriptor?.DisplayName?.ToLower() ?? string.Empty;
        var existGroup = groupApis.FirstOrDefault(s => displayName.Contains(s.ToLower()));
        return docName == existGroup;
    }

    return true;
});
  • RunSwagger 修改部分
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/v1/api-docs", "V1 Docs");
    //預設頁支持分組
    groupApis.ForEach(s =>
    {
        c.SwaggerEndpoint($"/{s}/api-docs", s);
    });
});
//單獨的頁面
groupApis.ForEach(s =>
{
    app.UseSwaggerUI(c =>
    {
        c.RoutePrefix = s;
        c.SwaggerEndpoint($"/{s}/api-docs", s);
    });
});
app.UseEndpoints(endpoints =>
{
    SwaggerUIOptions _options = new SwaggerUIOptions()
    {
        ConfigObject = new ConfigObject()
        {
            Urls = new List<UrlDescriptor>
                {
                    new UrlDescriptor()
                    {
                        Url="/v1/api-docs",
                        Name="V1 Docs"
                    }
                }.Concat(groupApis.Select(s => new UrlDescriptor()
                        {
                            Url = $"/{s}/api-docs",
                            Name = s
                        }).ToList())
        }
    };
})

修改完成後,可以結合自己業務來定義需要單獨顯示分組,最近又基於此加了一個開放平臺的介面,獨立於正常網關,單獨提供出去,一切都是剛剛好~

後語

如果有更好的方式,歡迎分享
若有錯誤,歡迎指出,謝謝

相關文檔

未經許可,禁止轉載!!!
作者:易墨
Github:yimogit
純靜態工具站點:metools


您的分享是我們最大的動力!

-Advertisement-
Play Games
更多相關文章
  • ★ JWT基本概念 JWT(JSON Web Token)是一種用於在網路應用之間傳遞信息的安全方式。它是一種基於 JSON 的開放標準(RFC 7519),用於在網路應用之間安全地傳輸聲明。JWT 通常用於身份驗證和授權,以及在分散式系統中傳遞聲明。 ★ JWT組成部分 JWT 由三部分組成:頭部 ...
  • 什麼是監視器(Monitor)? 在Java中,監視器(Monitor)是用來實現線程同步的一種機制。每個Java對象都有一個與之關聯的監視器,線程可以通過synchronized關鍵字來獲取和釋放對象的監視器。監視器的主要作用是確保在同一時刻只有一個線程可以執行同步塊或同步方法,從而實現線程的互斥 ...
  • ★ 背景說明 在Django REST framework (DRF) 前後端分離項目中,解決CSRF問題通常有以下幾種方法: 1. 禁用CSRF驗證,但這會降低安全性。(不推薦) 2. 使用csrftoken cookie 3. 在前端每次 POST、PUT 或 DELETE 請求前先發起一個GE ...
  • 數字簽名作為PDF文檔中的重要安全機制,不僅能夠驗證文件的來源,還能確保文件內容在傳輸過程中未被篡改。然而,如何正確驗證PDF文件的數字簽名,是確保文件完整性和可信度的關鍵。本文將詳細介紹如何使用免費.NET控制項通過C#驗證PDF簽名的有效性以及驗證PDF文檔是否被修改。 C# 驗證PDF數字簽名有 ...
  • 一、WTM是什麼 WalkingTec.Mvvm框架(簡稱WTM)最早開發與2013年,基於Asp.net MVC3 和 最早的Entity Framework, 當初主要是為瞭解決公司內部開發效率低,代碼風格不統一的問題。2017年9月,將代碼移植到了.Net Core上,併進行了深度優化和重構, ...
  • 實現了一個支持長短按得按鈕組件,單擊可以觸發Click事件,長按可以觸發LongPressed事件,長按鬆開時觸發LongClick事件。還可以和自定義外觀相結合,實現自定義的按鈕外形。 ...
  • WPF的按鈕提供了Template模板,可以通過修改Template模板中的內容對按鈕的樣式進行自定義。結合資源字典,可以將自定義資源在xaml視窗、自定義控制項或者整個App當中調用 ...
  • 在 Visual Studio 中,至少可以創建三種不同類型的類庫: 類庫(.NET Framework) 類庫(.NET 標準) 類庫 (.NET Core) 雖然第一種是我們多年來一直在使用的,但一直感到困惑的一個主要問題是何時使用 .NET Standard 和 .NET Core 類庫類型。 ...
一周排行
    -Advertisement-
    Play Games
  • 通過WPF的按鈕、文本輸入框實現了一個簡單的SpinBox數字輸入用戶組件並可以通過數據綁定數值和步長。本文中介紹了通過Xaml代碼實現自定義組件的佈局,依賴屬性的定義和使用等知識點。 ...
  • 以前,我看到一個朋友在對一個系統做初始化的時候,通過一組魔幻般的按鍵,調出來一個隱藏的系統設置界面,這個界面在常規的菜單或者工具欄是看不到的,因為它是一個後臺設置的關鍵界面,不公開,同時避免常規用戶的誤操作,它是作為一個超級管理員的入口功能,這個是很不錯的思路。其實Winform做這樣的處理也是很容... ...
  • 一:背景 1. 講故事 前些天有位朋友找到我,說他的程式每次關閉時就會自動崩潰,一直找不到原因讓我幫忙看一下怎麼回事,這位朋友應該是第二次找我了,分析了下 dump 還是挺經典的,拿出來給大家分享一下吧。 二:WinDbg 分析 1. 為什麼會崩潰 找崩潰原因比較簡單,用 !analyze -v 命 ...
  • 在一些報表模塊中,需要我們根據用戶操作的名稱,來動態根據人員姓名,更新報表的簽名圖片,也就是電子手寫簽名效果,本篇隨筆介紹一下使用FastReport報表動態更新人員簽名圖片。 ...
  • 最新內容優先發佈於個人博客:小虎技術分享站,隨後逐步搬運到博客園。 創作不易,如果覺得有用請在Github上為博主點亮一顆小星星吧! 博主開始學習編程於11年前,年少時還只會使用cin 和cout ,給單片機點點燈。那時候,類似async/await 和future/promise 模型的認知還不是 ...
  • 之前在阿裡雲ECS 99元/年的活動實例上搭建了一個測試用的MINIO服務,以前都是直接當基礎設施來使用的,這次準備自己學一下S3相容API相關的對象存儲開發,因此有了這個小工具。目前僅包含上傳功能,後續計劃開發一個類似圖床的對象存儲應用。 ...
  • 目錄簡介快速入門安裝 NuGet 包實體類User資料庫類DbFactory增刪改查InsertSelectUpdateDelete總結 簡介 NPoco 是 PetaPoco 的一個分支,具有一些額外的功能,截至現在 github 星數 839。NPoco 中文資料沒多少,我是被博客園群友推薦的, ...
  • 前言 前面使用 Admin.Core 的代碼生成器生成了通用代碼生成器的基礎模塊 分組,模板,項目,項目模型,項目欄位的基礎功能,本篇繼續完善,實現最核心的模板生成功能,並提供生成預覽及代碼文件壓縮下載 準備 首先清楚幾個模塊的關係,如何使用,簡單畫一個流程圖 前面完成了基礎的模板組,模板管理,項目 ...
  • 假設需要實現一個圖標和文本結合的按鈕 ,普通做法是 直接重寫該按鈕的模板; 如果想作為通用的呢? 兩種做法: 附加屬性 自定義控制項 推薦使用附加屬性的形式 第一種:附加屬性 創建Button的附加屬性 ButtonExtensions 1 public static class ButtonExte ...
  • 在C#中,委托是一種引用類型的數據類型,允許我們封裝方法的引用。通過使用委托,我們可以將方法作為參數傳遞給其他方法,或者將多個方法組合在一起,從而實現更靈活的編程模式。委托類似於函數指針,但提供了類型安全和垃圾回收等現代語言特性。 基本概念 定義委托 定義委托需要指定它所代表的方法的原型,包括返回類 ...