從零開始搭建前後端分離的NetCore2.2(EF Core CodeFirst+Autofac)+Vue的項目框架之十一Swagger使用一

来源:https://www.cnblogs.com/levywang/archive/2019/11/22/coreframe_11.html
-Advertisement-
Play Games

一.未使用Swagger狀況 相信無論是前端開發人員還是後端開發人員,都或多或少都被介面文檔折磨過,前端經常抱怨後端給的介面文檔或與實際情況不一致。後端又覺得編寫及維護介面文檔會耗費不少精力,經常來不及更新。 其實無論是前端調用後端,還是後端調用後端,都期望有一個好的介面文檔。但是這個介面文檔對於程 ...


 一.未使用Swagger狀況

  相信無論是前端開發人員還是後端開發人員,都或多或少都被介面文檔折磨過,前端經常抱怨後端給的介面文檔或與實際情況不一致。後端又覺得編寫及維護介面文檔會耗費不少精力,經常來不及更新。 其實無論是前端調用後端,還是後端調用後端,都期望有一個好的介面文檔。但是這個介面文檔對於程式員來說,就跟註釋一樣,經常會抱怨別人寫的代碼沒有寫註釋,然而自己寫起代碼起來,最討厭的,也是寫註釋。 所以僅僅只通過強制來規範大家是不夠的,隨著時間推移,版本迭代,介面文檔往往很容易就跟不上代碼了

 二.使用Swagger狀況

  Swagger 提供了一個可視化的UI頁面展示描述文件,其中包括介面的調用,介面所需參數(header,body,url.params),介面說明,參數說明等。介面的調用方、測試、項目經理等都可以在該頁面中對相關介面進行查閱和做一些簡單的介面請求。只要在項目框架搭建時,對Swagger 進行了配置,後面持續迭代的時候,只會花很小代價去維護代碼、介面文檔以及Swagger描述文件。因為一旦介面發生改變,程式重新部署,介面文檔會重新生成對應新的文檔。

 三.如何使用?

  在NetCore項目中怎麼去使用Swagger來生成介面文檔呢?

  首先在 webApi 啟動項目 上 右鍵 點擊管理Nuget程式包, 安裝  Swashbuckle.AspNetCore ,然後到  Startup 中添加引用  using Swashbuckle.AspNetCore.Swagger; 

  在ConfigureServices方法中添加以下代碼

            #region Swagger

            services.AddSwaggerGen(options =>
            {
                options.SwaggerDoc("v1", new Info
                {
                    Version = "v1",
                    Title = "API Doc",
                    Description = "作者:Levy_w_Wang",
                    //服務條款
                    TermsOfService = "None",
                    //作者信息
                    Contact = new Contact
                    {
                        Name = "levy",
                        Email = "[email protected]",
                        Url = "https://www.cnblogs.com/levywang"
                    },
                    //許可證
                    License = new License
                    {
                        Name = "tim",
                        Url = "https://www.cnblogs.com/levywang"
                    }
                });

                #region XmlComments

                var basePath1 = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程式所在目錄(絕對,不受工作目錄(平臺)影響,建議採用此方法獲取路徑)
                //獲取目錄下的XML文件 顯示註釋等信息
                var xmlComments = Directory.GetFiles(basePath1, "*.xml", SearchOption.AllDirectories).ToList();

                foreach (var xmlComment in xmlComments)
                {
                    options.IncludeXmlComments(xmlComment);
                }
                #endregion

                options.DocInclusionPredicate((docName, description) => true);

                options.IgnoreObsoleteProperties();//忽略 有Obsolete 屬性的方法
                options.IgnoreObsoleteActions();
                options.DescribeAllEnumsAsStrings();
            });
            #endregion

上面寫的迴圈是因為項目中可能有多個控制器類庫,為的是排除這種情況

接下來,再到 Configure 方法中添加:

            #region Swagger

            app.UseSwagger(c => { c.RouteTemplate = "apidoc/{documentName}/swagger.json"; });
            app.UseSwaggerUI(c =>
            {
                c.RoutePrefix = "apidoc";
                c.SwaggerEndpoint("v1/swagger.json", "ContentCenter API V1");
                c.DocExpansion(DocExpansion.Full);//預設文檔展開方式
            });

            #endregion

這裡使用了 RoutePrefix  屬性,為的是改變原始打開介面文檔目錄,原始路徑為 swagger/index.html ,現在為 /apidoc/index.html 

這個時候在需要輸出註釋的控制器類庫屬性 中設置如下信息,並添加上相關註釋

然後運行起來,打開本地地址加上  /apidoc/index.html  就可以看到效果,

特別提醒:如果打開下麵這個界面能正常顯示,但是提示  Fetch errorInternal Server Error v1/swagger.json  錯誤,說明有方法未指明請求方式,如 HttpGet HttpPost HttpPut 等,找到並指明,重新運行就正常了

 

  點擊方法右上角的 Try it out ,試下調用介面,然後點擊Exectue,執行查看結果,能得到後端方法返回結果就說明成功。

特別說明:有介面不需要展示出去的時候,可以在方法上添加屬性 Obsolete ,這樣就不會顯示出來。 前提:有前面ConfigureServices中 後面的 忽略 有Obsolete 屬性的方法 設置才行!!!

 

 最後可以看到介面返回數據正常,並且也能看到介面響應請求嘛等等信息,一個介面應該返回的信息也都有顯示。

 

總結:

本文從為開發人員手寫api文檔的痛楚,從而引申出Swagger根據代碼自動生成出文檔和註釋,

並且還可以將不需要的方法不顯示等設置。然後進行了簡單的測試使用 。

但是!!一般後端方法都有token等驗證,需要在header中添加token、sid等欄位來驗證用戶,保障安全性,

該設置將在下一章節中寫!

 

以上若有什麼不對或可以改進的地方,望各位指出或提出意見,一起探討學習~

有需要源碼的可通過此 GitHub 鏈接拉取 覺得還可以的給個 start 和點個 下方的推薦哦~~謝謝!

 


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

-Advertisement-
Play Games
更多相關文章
  • 前言 文的文字及圖片來源於網路,僅供學習、交流使用,不具有任何商業用途,版權歸原作者所有,如有問題請及時聯繫我們以作處理。 作者: 開源最前線(ID:OpenSourceTop) PS:如有需要Python學習資料的小伙伴可以加點擊下方鏈接自行獲取 http://note.youdao.com/no ...
  • redis Redis 基本介紹 redis是nosql型資料庫,不是傳統的資料庫,性能很高,適合做緩存也適合做出持久化,,完全開源免費,高性能的分散式記憶體資料庫,,基於記憶體運行,並支持持久化,,最熱門的nosql資料庫之一,也稱為數據結構伺服器。 redis 兩種安裝方式,壓縮包型,和,安裝文件型 ...
  • 因為String是非常常用的類, jvm對其進行了優化, jdk7之前jvm維護了很多的字元串常量在方法去的常量池中, jdk後常量池遷移到了堆中 方法區是一個運行時JVM管理的記憶體區域,是一個線程共用的記憶體區域,它用於存儲已被虛擬機載入的類信息、常量、靜態常量等。 使用引號來創建字元串 單獨(註意 ...
  • MiniProfiler 是一款性能分析的輕量級程式,可以基於action(request)記錄每個階段的耗時時長,還是可以顯示訪問資料庫時的SQL(支持EF、EF Code First)等 一、安裝程式包 通過Nuget安裝MiniProfiler : Install-Package MiniPr ...
  • 第一次寫隨筆,一名在實習的程式猿,做的一個小應用,需要的朋友可以參考參考, 使用WinForm實現了一個導入Excel,群發工資條的功能。功能已經實現,還不夠完善,。 大致運用了OleDbConnection,SMTP OleDbConnection來動態獲取Excel的數據 SMTP發郵件 簡單郵 ...
  • C#值類型和引用類型這個概念在剛學習的時候應該就知道了。但是我們並沒有深入的去理解它。越是基礎知識其實才是最有用的。對代碼的優化,代碼質量的提升都有幫助。通過整理本文章,對很多知識也起到了鞏固的作用吧。 1,值類型 值類型有:整型,浮點型,十進位,布爾型,struct,枚舉。值類型是線上程棧上分配的 ...
  • 1、公眾號配置坑--Token Token坑的自己弄個伺服器的地址和代碼,讓微信爸爸能訪問到。 例子: /// <summary>/// token驗證/// </summary>/// <param name="signature">signature結合了開發者填寫的token參數和請求中的ti ...
  • Swagger 是一款自動生成線上介面文檔+功能測試功能軟體 一、安裝程式包 通過管理 NuGet 程式包安裝,搜索Swashbuckle.AspNetCore 二、配置 Swagger 將 Swagger 添加到 Startup.ConfigureServices 方法中的服務集合中: 1 //註 ...
一周排行
    -Advertisement-
    Play Games
  • 移動開發(一):使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說,近來想嘗試開發一款安卓APP,考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP,畢竟是使用Visual Studio開發工具,使用起來也比較的順手,結合微軟官方的教程進行了安卓 ...
  • 前言 QuestPDF 是一個開源 .NET 庫,用於生成 PDF 文檔。使用了C# Fluent API方式可簡化開發、減少錯誤並提高工作效率。利用它可以輕鬆生成 PDF 報告、發票、導出文件等。 項目介紹 QuestPDF 是一個革命性的開源 .NET 庫,它徹底改變了我們生成 PDF 文檔的方 ...
  • 項目地址 項目後端地址: https://github.com/ZyPLJ/ZYTteeHole 項目前端頁面地址: ZyPLJ/TreeHoleVue (github.com) https://github.com/ZyPLJ/TreeHoleVue 目前項目測試訪問地址: http://tree ...
  • 話不多說,直接開乾 一.下載 1.官方鏈接下載: https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe,運行開始下載SQL server; 二. ...
  • 前言 隨著物聯網(IoT)技術的迅猛發展,MQTT(消息隊列遙測傳輸)協議憑藉其輕量級和高效性,已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫,為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog支持多種接收器用於日誌存儲,增強器用於添加屬性,LogContext管理動態屬性,支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項,適用於不同需求。 ...
  • 目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據,爬取信息時需要模擬瀏覽器行為,否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下: 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • 1.前言 什麼是熱更新 游戲或者軟體更新時,無需重新下載客戶端進行安裝,而是在應用程式啟動的情況下,在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR,Xlua,ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles,Addressable, ...
  • 本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺,其實像阿裡雲,騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後,它會送 ...
  • 通過以下方式可以高效,並保證數據同步的可靠性 1.API設計 使用RESTful設計,確保API端點明確,並使用適當的HTTP方法(如POST用於創建,PUT用於更新)。 設計清晰的請求和響應模型,以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證,確保接收到的數據符合預期格 ...