SpringBoot中優雅的使用Swagger2

来源:https://www.cnblogs.com/flyingDragon/archive/2020/07/05/13252137.html
-Advertisement-
Play Games

前言 Spring Boot 框架是目前非常流行的微服務框架,我們很多情況下使用它來提供 Rest API。而對於 Rest API 來說很重要的一部分內容就是文檔,Swagger 為我們提供了一套通過代碼和註解自動生成文檔的方法,這一點對於保證 API 文檔的及時性將有很大的幫助。本文將使用 Sw ...


前言

  Spring Boot 框架是目前非常流行的微服務框架,我們很多情況下使用它來提供 Rest API。而對於 Rest API 來說很重要的一部分內容就是文檔,Swagger 為我們提供了一套通過代碼和註解自動生成文檔的方法,這一點對於保證 API 文檔的及時性將有很大的幫助。本文將使用 Swagger 2 規範的 Springfox 實現來瞭解如何在 Spring Boot 項目中使用 Swagger,主要包含瞭如何使用 Swagger 自動生成文檔、使用 Swagger 文檔以及 Swagger 相關的一些高級配置和註解。

Swagger 簡介

Swagger 是一套基於 OpenAPI 規範構建的開源工具,可以幫助我們設計、構建、記錄以及使用 Rest API。Swagger 主要包含了以下三個部分:

  1. Swagger Editor:基於瀏覽器的編輯器,我們可以使用它編寫我們 OpenAPI 規範。

  2. Swagger UI:它會將我們編寫的 OpenAPI 規範呈現為互動式的 API 文檔,後文我將使用瀏覽器來查看並且操作我們的 Rest API。

  3. Swagger Codegen:它可以通過為 OpenAPI(以前稱為 Swagger)規範定義的任何 API 生成伺服器存根和客戶端 SDK 來簡化構建過程。

為什麼要使用 Swagger

當下很多公司都採取前後端分離的開發模式,前端和後端的工作由不同的工程師完成。在這種開發模式下,維持一份及時更新且完整的 Rest API 文檔將會極大的提高我們的工作效率。傳統意義上的文檔都是後端開發人員手動編寫的,相信大家也都知道這種方式很難保證文檔的及時性,這種文檔久而久之也就會失去其參考意義,反而還會加大我們的溝通成本。而 Swagger 給我們提供了一個全新的維護 API 文檔的方式,下麵我們就來瞭解一下它的優點:

  1. 代碼變,文檔變。只需要少量的註解,Swagger 就可以根據代碼自動生成 API 文檔,很好的保證了文檔的時效性。

  2. 跨語言性,支持 40 多種語言。

  3. Swagger UI 呈現出來的是一份可互動式的 API 文檔,我們可以直接在文檔頁面嘗試 API 的調用,省去了準備複雜的調用參數的過程。

  4. 還可以將文檔規範導入相關的工具(例如 SoapUI), 這些工具將會為我們自動地創建自動化測試。

以上這些優點足以說明我們為什麼要使用 Swagger 了,您是否已經對 Swagger 產生了濃厚的興趣了呢?下麵我們就將一步一步地在 Spring Boot 項目中集成和使用 Swagger,讓我們從準備一個 Spring Boot 的 Web 項目開始吧。

SpringBoot整合Swagger2

  1. 首先創建一個基礎的SpringBoot web項目。您可以通過 Spring Initializr 頁面生成一個空的 Spring Boot 項目,或者通過idea創建一個SpringBoot項目

  2. 添加依賴

    1. Spring Boot 的 Web 依賴 
      <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
      </dependency>
    2. 集成swagger2 
      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
      </dependency>
    3. 集成Swagger UI
      <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
      </dependency>
  3. java中Swagger2配置-直接上配置代碼,Swagger2的配置是比較容易的,在成功項目創建之後,只需要開發者自己提供一個Docket的Bean。(註釋寫的很清楚,這裡就不一一解釋了。不懂的地方可以在片尾關註我公眾號加我WX。)

    /**
     * 集成swagger2  解決前後端分離 弊端:不能及時協商+今早解決的問題
     *      使用swagger總結:
     *          通過swagger 給一些比基奧難理解的介面或屬性,增加註釋信息
     *          介面文檔實時更新
     *          可以線上測試
     *      安全問題:
     *          正式上線的時候  記得關閉swagger
     */
    @Configuration//載入到springboot配置裡面
    @EnableSwagger2//開啟swagger2
    public class SwaggerConfig {
        /**
         * 配置swagger2
         * 註冊一個bean屬性
         * swagger2其實就是重新寫一個構造器,因為他沒有get set方法\
         * enable() 是否啟用swagger false swagger不能再瀏覽器中訪問
         * groupName()配置api文檔的分組  那就註冊多個Docket實例 相當於多個分組
         * @return
         */
        @Bean
        public Docket docket() {
    ​
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .groupName("XXX")//組名稱
                    .enable(true)
                    .select()
                    /**
                     * RequestHandlerSelectors配置掃描介面的方式
                     *      basePackage 配置要掃描的包
                     *      any 掃描全部
                     *      none 不掃描
                     *      withClassAnnotation 掃描類上的註解
                     *      withMethodAnnotation 掃描方法上的註解
                     */
                    .apis(RequestHandlerSelectors.basePackage("com.tinygray.madison.controller"))
                    /**
                     * paths() 掃描過濾方式
                     *      any過濾全部
                     *      none不過濾
                     *      regex正則過濾
                     *      ant過濾指定路徑
                     */
    //                .paths(PathSelectors.ant("/login/**"))
                    .build();
        }
    ​
        /**
         * 配置swagger2信息 =apiInfo
         * @return
         */
        public ApiInfo apiInfo(){
            /*作者信息*/
    //        Contact contact = new Contact("XXX", "http://baidu.com", "email");
            Contact contact = new Contact("", "", "");
            return new ApiInfo(
                    "XXX的API介面",
                    "company介面",
                    "V1.0",
                    "urn:toVs",
                    contact,
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LICENSE-2.0",
                    new ArrayList());
        }
    ​
    }

     

  4. 編寫一些簡單的java介面。(你可以根據你的情況進行編寫)
    @Api(tags = "TestController測試")
    @RestController
    public class TestController {
        @ApiOperation("login api")
        @GetMapping("/")
        public String login() {
            return "Hello login ~";
        }
    ​
        @ApiOperation("helloWord Api")
        @GetMapping("/index")
        public String index() {
            return "Hello World ~";
        }
    ​
        @ApiOperation("admin Api")
        @GetMapping("/admin/hello")
        public String admin() {
            return "hello admin!";
        }
    ​
        @ApiOperation("user Api")
        @GetMapping("/user/hello")
        public String user() {
            return "hello user";
        }
    }
  5. 驗證代碼-到這裡我們已經成功集成Swagger2,然後啟動項目,輸入http://localhost:8080/swagger-ui.html,如果能出現下麵界面,說明配置成功了。
  6. 未完待續。下章節講解Swagger的常用註解。

    這篇文章是否幫助到你呢?掃描關註公眾號--【Madison龍少】,【Madison龍少】公眾號每天提供java乾貨,乾貨滿滿。


 


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

-Advertisement-
Play Games
更多相關文章
  • 在“JavaScript圖形實例:SierPinski三角形” 和“JavaScript圖形實例:Levy曲線及其變形”等文章中我們介紹了通過遞歸生成分形圖形的方法。我們可以將繪製的分形圖形每隔一定的時間間隔後,增加遞歸深度重新繪製一次,這樣就可以得到分形圖形的動態生成效果。 1.SierPinsk ...
  • Nuxt 是 Vue 項目伺服器端渲染(SSR)解決方案。而在使用時,就會遇到前後端分離情況下的功能變數名稱或埠不一致導致的跨域問題。本文將介紹如何通過設置代理解決 Nuxt 與 axios 集成的跨域問題。 ...
  • Electron是一個可以使用 JavaScript,HTML 和 CSS 構建跨平臺桌面應用程式的開源框架。 本文主要分享一下採用vue + electron開發桌面程式的搭建過程。 1. 環境準備 這裡採用的是vue-cli3.x,可以通過下麵的指令查看當前vue-cli的版本: vue --v ...
  • #讀後感# 《企業IT架構轉型之道-阿裡巴巴中台戰略思想與架構實戰》鐘華(花名:古謙)編著,阿裡巴巴中間件首席架構師,15年中間件領域行業經驗。 進入新公司第一天,領導就給了這本書,慚愧,剛看完... 一本推動“中台建設”指導性實戰用書,濃縮了10來年的經驗,從架構層面詳細敘述阿裡共用業務事業部:技 ...
  • 抽象工廠模式 優化抽象工廠 非同步工廠 在學習抽象工廠模式前,先來回顧一下前面的簡單工廠和工廠方法模式。簡單工廠的職責非常簡單:構造某個實體類型,然後把實例作為抽象類型返回; 工廠方法模式則進一步抽象出一個抽象的創建者和一個抽象的產品類型,而實際的執行過程是具體工廠創建具體的產品類型,具體工廠和具體產 ...
  • 我的LeetCode:https://leetcode-cn.com/u/ituring/ 我的LeetCode刷題源碼[GitHub]:https://github.com/izhoujie/Algorithmcii LeetCode 題目 字元串有三種編輯操作:插入一個字元、刪除一個字元或者替換 ...
  • 問題來源: 在寫二叉樹序列化與反序列化時發現序列化函數為char* Serialize1(TreeNode *root) 其函數返回類型為char*,但是我在實現的過程中為了更方便的操作添加字元串使用的是C++中string類型的變數,這就導致我最後得到的結果res是string類型,若是要返回需要 ...
  • C#與python的迭代器比較: 迭代器 C# Python 一個對象可迭代,需要實現IEnumerable(表示對象可數),IEnumerable就是要實現一個IEnumerator(迭代對象)。 這樣的說法曾經一度讓我很迷,如果返回一個已實現的類似於數組array、列表list類型的IEnume ...
一周排行
    -Advertisement-
    Play Games
  • Timer是什麼 Timer 是一種用於創建定期粒度行為的機制。 與標準的 .NET System.Threading.Timer 類相似,Orleans 的 Timer 允許在一段時間後執行特定的操作,或者在特定的時間間隔內重覆執行操作。 它在分散式系統中具有重要作用,特別是在處理需要周期性執行的 ...
  • 前言 相信很多做WPF開發的小伙伴都遇到過表格類的需求,雖然現有的Grid控制項也能實現,但是使用起來的體驗感並不好,比如要實現一個Excel中的表格效果,估計你能想到的第一個方法就是套Border控制項,用這種方法你需要控制每個Border的邊框,並且在一堆Bordr中找到Grid.Row,Grid. ...
  • .NET C#程式啟動閃退,目錄導致的問題 這是第2次踩這個坑了,很小的編程細節,容易忽略,所以寫個博客,分享給大家。 1.第一次坑:是windows 系統把程式運行成服務,找不到配置文件,原因是以服務運行它的工作目錄是在C:\Windows\System32 2.本次坑:WPF桌面程式通過註冊表設 ...
  • 在分散式系統中,數據的持久化是至關重要的一環。 Orleans 7 引入了強大的持久化功能,使得在分散式環境下管理數據變得更加輕鬆和可靠。 本文將介紹什麼是 Orleans 7 的持久化,如何設置它以及相應的代碼示例。 什麼是 Orleans 7 的持久化? Orleans 7 的持久化是指將 Or ...
  • 前言 .NET Feature Management 是一個用於管理應用程式功能的庫,它可以幫助開發人員在應用程式中輕鬆地添加、移除和管理功能。使用 Feature Management,開發人員可以根據不同用戶、環境或其他條件來動態地控制應用程式中的功能。這使得開發人員可以更靈活地管理應用程式的功 ...
  • 在 WPF 應用程式中,拖放操作是實現用戶交互的重要組成部分。通過拖放操作,用戶可以輕鬆地將數據從一個位置移動到另一個位置,或者將控制項從一個容器移動到另一個容器。然而,WPF 中預設的拖放操作可能並不是那麼好用。為瞭解決這個問題,我們可以自定義一個 Panel 來實現更簡單的拖拽操作。 自定義 Pa ...
  • 在實際使用中,由於涉及到不同編程語言之間互相調用,導致C++ 中的OpenCV與C#中的OpenCvSharp 圖像數據在不同編程語言之間難以有效傳遞。在本文中我們將結合OpenCvSharp源碼實現原理,探究兩種數據之間的通信方式。 ...
  • 一、前言 這是一篇搭建許可權管理系統的系列文章。 隨著網路的發展,信息安全對應任何企業來說都越發的重要,而本系列文章將和大家一起一步一步搭建一個全新的許可權管理系統。 說明:由於搭建一個全新的項目過於繁瑣,所有作者將挑選核心代碼和核心思路進行分享。 二、技術選擇 三、開始設計 1、自主搭建vue前端和. ...
  • Csharper中的表達式樹 這節課來瞭解一下表示式樹是什麼? 在C#中,表達式樹是一種數據結構,它可以表示一些代碼塊,如Lambda表達式或查詢表達式。表達式樹使你能夠查看和操作數據,就像你可以查看和操作代碼一樣。它們通常用於創建動態查詢和解析表達式。 一、認識表達式樹 為什麼要這樣說?它和委托有 ...
  • 在使用Django等框架來操作MySQL時,實際上底層還是通過Python來操作的,首先需要安裝一個驅動程式,在Python3中,驅動程式有多種選擇,比如有pymysql以及mysqlclient等。使用pip命令安裝mysqlclient失敗應如何解決? 安裝的python版本說明 機器同時安裝了 ...