基於 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 ...
一周排行
  • 比如要拆分“呵呵呵90909086676喝喝999”,下麵當type=0返回的是中文字元串“呵呵呵,喝喝”,type=1返回的是數字字元串“90909086676,999”, private string GetStrings(string str,int type=0) { IList<strin ...
  • Swagger一個優秀的Api介面文檔生成工具。Swagger可以可以動態生成Api介面文檔,有效的降低前後端人員關於Api介面的溝通成本,促進項目高效開發。 1、使用NuGet安裝最新的包:Swashbuckle.AspNetCore。 2、編輯項目文件(NetCoreTemplate.Web.c ...
  • 2020 年 7 月 30 日, 由.NET基金會和微軟 將舉辦一個線上和為期一天的活動,包括 微軟 .NET 團隊的演講者以及社區的演講者。本次線上大會 專註.NET框架構建微服務,演講者分享構建和部署雲原生應用程式的最佳實踐、模式、提示和技巧。有關更多信息和隨時瞭解情況:https://focu... ...
  • #abp框架Excel導出——基於vue #1.技術棧 ##1.1 前端採用vue,官方提供 UI套件用的是iview ##1.2 後臺是abp——aspnetboilerplate 即abp v1,https://github.com/aspnetboilerplate/aspnetboilerp ...
  • 前言 本文的文字及圖片來源於網路,僅供學習、交流使用,不具有任何商業用途,版權歸原作者所有,如有問題請及時聯繫我們以作處理。 作者:碧茂大數據 PS:如有需要Python學習資料的小伙伴可以加下方的群去找免費管理員領取 input()輸入 Python提供了 input() 內置函數從標準輸入讀入一 ...
  • 從12年到20年,python以肉眼可見的趨勢超過了java,成為了當今It界人人皆知的編程語言。 python為什麼這麼火? 網路編程語言搜索指數 適合初學者 Python具有語法簡單、語句清晰的特點,這就讓初學者在學習階段可以把精力集中在編程對象和思維方法上。 大佬都在用 Google,YouT ...
  • 在社會上存在一種普遍的對培訓機構的學生一種歧視的現象,具體表現在,比如:當你去公司面試的時候,一旦你說了你是培訓機構出來的,那麼基本上你就涼了,那麼你瞞著不說,然後又通過了面試成功入職,但是以後一旦在公司被髮現有培訓經歷,可能會面臨被降薪,甚至被辭退,培訓機構出來的學生,在用人單位眼裡就是能力低下的 ...
  • from typing import List# 這道題看了大佬寫的代碼,經過自己的理解寫出來了。# 從最外圍的四周找有沒有為O的,如果有的話就進入深搜函數,然後深搜遍歷# 判斷上下左右的位置是否為Oclass Solution: def solve(self, board: List[List[s ...
  • import requests; import re; import os; # 1.請求網頁 header = { "user-agent":'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, li ...
  • import requests; import re; import os; import parsel; 1.請求網頁 header = { "user-agent":'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537. ...