基於 abp vNext 和 .NET Core 開發博客項目 - 再說Swagger,分組、描述、小綠鎖

来源:https://www.cnblogs.com/meowv/archive/2020/05/22/12924859.html

在開始本篇正文之前,解決一個 @瘋瘋過 指出的錯誤,再次感謝指正。 步驟如下: 刪掉 層中的項目引用,添加nuget依賴包 ,可以使用命令: 在 層中引用項目 ,在模塊類中添加依賴 將 層中的引用項目 改成 。 上一篇文章(https://www.cnblogs.com/meowv/p/129244 ...


在開始本篇正文之前,解決一個 @瘋瘋過 指出的錯誤,再次感謝指正。

0

步驟如下:

  • 刪掉.Domain.Shared層中的項目引用,添加nuget依賴包Volo.Abp.Identity.Domain.Shared,可以使用命令:Install-Package Volo.Abp.Identity.Domain.Shared
  • .Domain層中引用項目.Domain.Shared,在模塊類中添加依賴typeof(MeowvBlogDomainSharedModule)
  • .EntityFrameworkCore層中的引用項目.Domain.Shared改成.Domain

0


上一篇文章(https://www.cnblogs.com/meowv/p/12924409.html)完成了對API返回模型的封裝,緊接著我打算繼續來折騰一下Swagger,之前的文章中已經簡單用起了Swagger,本篇還是圍繞它讓其發揮更高的更多的價值。

當我們的項目不斷壯大,API持續增多,這時如果想要快速準確定位到某個API可能不是那麼容易,需要翻半天才能找對我們的API。於是對Swagger API文檔分組和詳細的文檔描述就有必要了,就本項目而言,博客系統可以分組為:博客前臺介面、博客後臺介面、其它公共介面、JWT認證授權介面。

其中,博客後臺組中的介面需要授權後才可以調用,需要授權那麼就涉及到身份驗證,在這裡準備採用JWT(JSON WEB TOKEN)的方式進行。

分組

對Swagger進行分組很簡單,在.Swagger層中的擴展方法AddSwagger(this IServiceCollection services)中多次調用options.SwaggerDoc(...)即可,像這樣

...
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "1.0.0",
        Title = "我的介面啊1",
        Description = "介面描述1"
    });
    options.SwaggerDoc("v2", new OpenApiInfo
    {
        Version = "1.0.0",
        Title = "我的介面啊2",
        Description = "介面描述2"
    });
    ...
...

不過這樣顯得有點low,然後可以轉變一下思路使用遍歷的方式進行。options.SwaggerDoc(...)接收兩個參數:string name, OpenApiInfo info

name:可以理解為當前分組的首碼;OpenApiInfo:有許多可配置的參數,在這裡我只用到三個,VersionTitleDescription

要註意,當在AddSwagger(...)中調用完後,還需要在我們的擴展方法UseSwaggerUI(this IApplicationBuilder app)options.SwaggerEndpoint()使用它,同樣的也用遍歷的方法。它接收的的參數:string url, string name

url:這裡的url要與前面配置的name參數對應。

name:我們自定義顯示的分組名稱。

於是可以直接在擴展方法中新建一個內部類:SwaggerApiInfo

        internal class SwaggerApiInfo
        {
            /// <summary>
            /// URL首碼
            /// </summary>
            public string UrlPrefix { get; set; }

            /// <summary>
            /// 名稱
            /// </summary>
            public string Name { get; set; }

            /// <summary>
            /// <see cref="Microsoft.OpenApi.Models.OpenApiInfo"/>
            /// </summary>
            public OpenApiInfo OpenApiInfo { get; set; }
        }

然後新建一個List<SwaggerApiInfo>手動為其初始化一些值。

...
       /// <summary>
        /// Swagger分組信息,將進行遍歷使用
        /// </summary>
        private static readonly List<SwaggerApiInfo> ApiInfos = new List<SwaggerApiInfo>()
        {
            new SwaggerApiInfo
            {
                UrlPrefix = Grouping.GroupName_v1,
                Name = "博客前臺介面",
                OpenApiInfo = new OpenApiInfo
                {
                    Version = version,
                    Title = "阿星Plus - 博客前臺介面",
                    Description = description
                }
            },
            new SwaggerApiInfo
            {
                UrlPrefix = Grouping.GroupName_v2,
                Name = "博客後臺介面",
                OpenApiInfo = new OpenApiInfo
                {
                    Version = version,
                    Title = "阿星Plus - 博客後臺介面",
                    Description = description
                }
            },
            new SwaggerApiInfo
            {
                UrlPrefix = Grouping.GroupName_v3,
                Name = "通用公共介面",
                OpenApiInfo = new OpenApiInfo
                {
                    Version = version,
                    Title = "阿星Plus - 通用公共介面",
                    Description = description
                }
            },
            new SwaggerApiInfo
            {
                UrlPrefix = Grouping.GroupName_v4,
                Name = "JWT授權介面",
                OpenApiInfo = new OpenApiInfo
                {
                    Version = version,
                    Title = "阿星Plus - JWT授權介面",
                    Description = description
                }
            }
        };
...

version:我們將其配置在appsettings.json中,做到動態可以修改。

//AppSettings.cs
...
        /// <summary>
        /// ApiVersion
        /// </summary>
        public static string ApiVersion => _config["ApiVersion"];
...

//appsettings.json
{
...
  "ApiVersion": "1.0.0"
...
}

description:因為多次使用,就定義一個變數,內容自擬主要是一些介紹性的描述,將在Swagger界面進行顯示。

UrlPrefix:分別為,v1,v2,v3,v4。在Domain.Shared層中為其定義好常量

//MeowvBlogConsts.cs
...
        /// <summary>
        /// 分組
        /// </summary>
        public static class Grouping
        {
            /// <summary>
            /// 博客前臺介面組
            /// </summary>
            public const string GroupName_v1 = "v1";

            /// <summary>
            /// 博客後臺介面組
            /// </summary>
            public const string GroupName_v2 = "v2";

            /// <summary>
            /// 其他通用介面組
            /// </summary>
            public const string GroupName_v3 = "v3";

            /// <summary>
            /// JWT授權介面組
            /// </summary>
            public const string GroupName_v4 = "v4";
        }
...

現在修改擴展方法AddSwagger(...),遍歷List<SwaggerApiInfo>

...
        public static IServiceCollection AddSwagger(this IServiceCollection services)
        {
            return services.AddSwaggerGen(options =>
            {
                //options.SwaggerDoc("v1", new OpenApiInfo
                //{
                //    Version = "1.0.0",
                //    Title = "我的介面啊",
                //    Description = "介面描述"
                //});

                // 遍歷並應用Swagger分組信息
                ApiInfos.ForEach(x =>
                {
                    options.SwaggerDoc(x.UrlPrefix, x.OpenApiInfo);
                });
                ...
            });
        }
...

在擴展方法UseSwaggerUI(...)使用,通用也需要遍歷。

...
        // 遍歷分組信息,生成Json
        ApiInfos.ForEach(x =>
        {
                options.SwaggerEndpoint($"/swagger/{x.UrlPrefix}/swagger.json", x.Name);
        });
...

細心的同學可以發現,我們前幾篇文章打開Swagger文檔的時候都是需要手動更改URL地址:.../swagger才能正確進入,其實Swagger是支持配置路由的。同時咱們也將頁面Title也給改了吧。看下麵UseSwaggerUI(...)完整代碼:

...
        /// <summary>
        /// UseSwaggerUI
        /// </summary>
        /// <param name="app"></param>
        public static void UseSwaggerUI(this IApplicationBuilder app)
        {
            app.UseSwaggerUI(options =>
            {
                // 遍歷分組信息,生成Json
                ApiInfos.ForEach(x =>
                {
                    options.SwaggerEndpoint($"/swagger/{x.UrlPrefix}/swagger.json", x.Name);
                });

                // 模型的預設擴展深度,設置為 -1 完全隱藏模型
                options.DefaultModelsExpandDepth(-1);
                // API文檔僅展開標記
                options.DocExpansion(DocExpansion.List);
                // API首碼設置為空
                options.RoutePrefix = string.Empty;
                // API頁面Title
                options.DocumentTitle = "

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

更多相關文章
  • 同步版本示例: namespace SyncSample { class MyDownloadString { Stopwatch sw = new Stopwatch(); public void DoRun() { const int LargeNumber = 6000000; sw.Star ...
  • 在Linux上搭建基於開源技術的nuget私人保密倉庫 前言 在Linux上搭建nuget私人倉庫一直是一個老大難的問題,主要涉及到以下難點: nuget.org官方使用的Nuget.Server基於.NET Framework的ASP.NET,而不是ASP.NET Core,因此是Windows ...
  • 網上有很多Socket框架,但是我想,C#既然有Socket類,難道不是給人用的嗎? 寫了一個SocketServerHelper和SocketClientHelper,分別隻有5、6百行代碼,比不上大神寫的,和業務代碼耦合也比較重,但對新手非常友好,容易看懂。 支持返回值或回調,支持不定長度的數據 ...
  • 動手寫一個簡版 asp.net core Intro 之前看到過蔣金楠老師的一篇 200 行代碼帶你瞭解 asp.net core 框架,最近參考蔣老師和 Edison 的文章和代碼,結合自己對 asp.net core 的理解 ,最近自己寫了一個 MiniAspNetCore ,寫篇文章總結一下。 ...
  • 在微軟的Build 2020開發者大會中,微軟就正在成形的C#9.0的一些即將添加的主要特性進行了說明。 1.init屬性訪問器 對象初始化方式對於創建對象來說是一種非常靈活和可讀的格式,特別是對樹狀嵌入型對象的創建。簡單的例如 new Person { FirstName = "Scott", L ...
  • 作為一個老司機,怎能沒有自己的私人代碼倉庫? 前言 Github大家都熟悉。 除了開源的項目外,有時候,大家也會把自己或團隊、公司的項目傳到Github的私有倉庫里,把Github當成自己的私人Git Server。 但是,用Github會有一些問題: Github從國內訪問不是很穩定,有時候會很慢 ...
  • 前言 大概3個星期之前立項, 要做一個 CEF+Blazor+WinForms 三合一到同一個進程的客戶端模板. 這個東西在五一的時候做出了原型, 然後慢慢修正, 在5天之前就上傳到github了. 地址 : https://github.com/BlazorPlus/BlazorCefApp 但是 ...
  • 在開發環境的電腦上可生成報表,但是一到客戶端就提示An error occurred during local report processing錯誤。 我把 Microsoft.ReportViewer.Common.dll Microsoft.ReportViewer.WinForms.dll ...
一周排行
  • 一:背景 1. 講故事 曾今在項目中發現有同事自定義結構體的時候,居然沒有重寫Equals方法,比如下麵這段代碼: static void Main(string[] args) { var list = Enumerable.Range(0, 1000).Select(m => new Point ...
  • 最近一個朋友有個關於素數的小東西要寫一下,素數是什麼呢?除了1和他本身不能被其他數整除,那麼這個數就是素數,1除外哦。我們知道概念那就很簡單了,直接代碼擼起。 ...
  • 前言 在開發編程中,我們經常會遇到功能非常相似的功能模塊,只是他們的處理的數據不一樣,所以我們會分別採用多個方法來處理不同的數據類型。但是這個時候,我們就會想一個問題,有沒有辦法實現利用同一個方法來傳遞不同種類型的參數呢? 這個時候,泛型也就因運而生,專門來解決這個問題的。 泛型是在C 2.0就推出 ...
  • 本文章主要用於介紹在Asp.Net Mvc(C#)中使用Fleck製作一個Html5的即時聊天室,含有完整代碼和演示Demo。 ...
  • 出庫單的功能。能學習了出庫單管理之後,WMS的 主體功能算是完成了。當然一個成熟的WMS還包括了盤點,報表,策略規則,移庫功能及與其他系統(ERP、TMS等)的介面,實現無縫集成,打破信息孤島,讓數據實時、準確和同步。 ...
  • Data StructureThere're two types of variables in C#, reference type and value type.Enum:enum Color{Red=0,Green=1}//equals to enum Color{Red,//start fr... ...
  • 0. 前言 該項目使用Maven進行管理和構建,所以需要預先配置好Maven。嗯,在這個系列里就不做過多的介紹了。 1. 創建項目 先創建一個pom.xml 文件,添加以下內容: <?xml version="1.0" encoding="UTF-8"?> <project xmlns="http: ...
  • API 概述 API(Application Programming Interface),應用程式編程介面。 Java API是一本程式員的 字典 ,是JDK中提供給我們使用的類的說明文檔。 這些類將底層的代碼實現封裝了起來,我們不需要關心這些類是如何實現的,只需要學習這些類如何使用即可。 所以我 ...
  • 女程式員是這麼徵婚的: SELECT * FROM 男人們 WHERE 未婚=true and 同性戀=false and 有房=true and 有車=true and 條件 in (帥氣,紳士,大度,氣質,智慧,溫柔,體貼,會浪漫,活潑,可愛,最好還能帶孩子) and 年齡 between(24 ...
  • 有很多剛學習軟體測試的小伙伴,都會在網路上找尋各種學習資料,去提升自己的專業技能水平。因此,我決定定期分享我整理收集的一些軟體測試的測試工具下載、面試寶典、視頻教學合集。都整理好了,有需要的可以關註我(獲取方式在文末) 軟體測試的學習,不止是基礎理論,還需要學習測試工具的用法,如介面工具Postma ...