Springfox與SpringDoc——swagger如何選擇（SpringDoc入門）

来源:https://www.cnblogs.com/developer-tianyiyun/archive/2023/04/07/17296936.html
-Advertisement-
Play Games

本文分享自天翼雲開發者社區@《Springfox與SpringDoc——swagger如何選擇（SpringDoc入門）》，作者: 才開始學技術的小白 0.引言 之前寫過一篇關於swagger（實際上是springfox）的使用指南（https://www.ctyun.cn/developer/ar ...


 

本文分享自天翼雲開發者社區@《Springfox與SpringDoc——swagger如何選擇（SpringDoc入門）》，作者: 才開始學技術的小白

 

 

0.引言

之前寫過一篇關於swagger（實際上是springfox）的使用指南（https://www.ctyun.cn/developer/article/371704742199365），涵蓋了本人在開發與學習的時候碰到的各種大坑。但由於springfox已經不更新了，很多項目都在往springdoc遷移

筆者也是花了一些時間試了一下這個號稱“把springfox按在地下摩擦”的springdoc究竟好不好使，本文就來簡單介紹下springdoc的使用以及優劣勢

1.引入maven依賴

這裡有個大坑一定要註意！！！

如果你跟我一樣，現在使用的是springfox，但是想往springdoc遷移，結果試了一下發現還是springfox好用/懶得改那麼多註解，還是想換回springfox，一定要把springdoc的maven依賴刪掉！！！不然springboot會預設你用的是springdoc，導致swagger界面出不來

<dependency>

            <groupId>org.springdoc</groupId>

            <artifactId>springdoc-openapi-ui</artifactId>

            <version>1.6.11</version>

 </dependency>

2.springdoc配置類

實際上springdoc的配置非常簡單，使用的是OpenAPI類與GroupedOpenApi來配置

/**

 * SpringDoc API文檔相關配置

 * Created by macro on 2023/02/02.

 */@Configurationpublic class SpringDocConfig {

    @Bean

    public OpenAPI mallTinyOpenAPI() {

        return new OpenAPI()

                .info(new Info().title("CTYUN API")

                        .description("SpringDoc API 演示")

                        .version("v1.0.0")

                        .license(new License().name("Apache 2.0").url("https://github.com/")))

                .externalDocs(new ExternalDocumentation()

                        .description("SpringBoot項目")

                        .url("http://www.ctyun.com"));

    }

 

    @Bean

    public GroupedOpenApi adminApi() {

        return GroupedOpenApi.builder()

                .group("admin")

                .pathsToMatch("/**")

                .build();

    }

    //可以創建不同的GroupedOpenApi來判斷不同的controller

    @Bean

    public GroupedOpenApi userApi() {

        return GroupedOpenApi.builder()

                .group("user")

                .pathsToMatch("/user/**")

                .build();

    }}

3.啟動

預設配置之後直接進入：http://localhost:8080/swagger-ui/index.html 即可

註意這裡與springfox略有不同（http://localhost:8080/swagger-ui.html）

 

4.與SpringFox的註解對照

5.SpringDoc基本註解用法

這裡轉載一個寫的非常全面的示例介面，原文可以去看：https://blog.csdn.net/zhenghongcs/article/details/123812583

/**

 * 品牌管理Controller

 * Created by macro on 2019/4/19.

 */@Tag(name = "PmsBrandController", description = "商品品牌管理")@Controller@RequestMapping("/brand")public class PmsBrandController {

    @Autowired

    private PmsBrandService brandService;

    private static final Logger LOGGER = LoggerFactory.getLogger(PmsBrandController.class);

    @Operation(summary = "獲取所有品牌列表",description = "需要登錄後訪問")

    @RequestMapping(value = "listAll", method = RequestMethod.GET)

    @ResponseBody

    public CommonResult<List<PmsBrand>> getBrandList() {

        return CommonResult.success(brandService.listAllBrand());

    }

 

    @Operation(summary = "添加品牌")

    @RequestMapping(value = "/create", method = RequestMethod.POST)

    @ResponseBody

    @PreAuthorize("hasRole('ADMIN')")

    public CommonResult createBrand(@RequestBody PmsBrand pmsBrand) {

        CommonResult commonResult;

        int count = brandService.createBrand(pmsBrand);

        if (count == 1) {

            commonResult = CommonResult.success(pmsBrand);

            LOGGER.debug("createBrand success:{}", pmsBrand);

        } else {

            commonResult = CommonResult.failed("操作失敗");

            LOGGER.debug("createBrand failed:{}", pmsBrand);

        }

        return commonResult;

    }

 

    @Operation(summary = "更新指定id品牌信息")

    @RequestMapping(value = "/update/{id}", method = RequestMethod.POST)

    @ResponseBody

    @PreAuthorize("hasRole('ADMIN')")

    public CommonResult updateBrand(@PathVariable("id") Long id, @RequestBody PmsBrand pmsBrandDto, BindingResult result) {

        CommonResult commonResult;

        int count = brandService.updateBrand(id, pmsBrandDto);

        if (count == 1) {

            commonResult = CommonResult.success(pmsBrandDto);

            LOGGER.debug("updateBrand success:{}", pmsBrandDto);

        } else {

            commonResult = CommonResult.failed("操作失敗");

            LOGGER.debug("updateBrand failed:{}", pmsBrandDto);

        }

        return commonResult;

    }

 

    @Operation(summary = "刪除指定id的品牌")

    @RequestMapping(value = "/delete/{id}", method = RequestMethod.GET)

    @ResponseBody

    @PreAuthorize("hasRole('ADMIN')")

    public CommonResult deleteBrand(@PathVariable("id") Long id) {

        int count = brandService.deleteBrand(id);

        if (count == 1) {

            LOGGER.debug("deleteBrand success :id={}", id);

            return CommonResult.success(null);

        } else {

            LOGGER.debug("deleteBrand failed :id={}", id);

            return CommonResult.failed("操作失敗");

        }

    }

 

    @Operation(summary = "分頁查詢品牌列表")

    @RequestMapping(value = "/list", method = RequestMethod.GET)

    @ResponseBody

    @PreAuthorize("hasRole('ADMIN')")

    public CommonResult<CommonPage<PmsBrand>> listBrand(@RequestParam(value = "pageNum", defaultValue = "1")

                                                        @Parameter(description = "頁碼") Integer pageNum,

                                                        @RequestParam(value = "pageSize", defaultValue = "3")

                                                        @Parameter(description = "每頁數量") Integer pageSize) {

        List<PmsBrand> brandList = brandService.listBrand(pageNum, pageSize);

        return CommonResult.success(CommonPage.restPage(brandList));

    }

 

    @Operation(summary = "獲取指定id的品牌詳情")

    @RequestMapping(value = "/{id}", method = RequestMethod.GET)

    @ResponseBody

    @PreAuthorize("hasRole('ADMIN')")

    public CommonResult<PmsBrand> brand(@PathVariable("id") Long id) {

        return CommonResult.success(brandService.getBrand(id));

    }}

6.與SpringSecurity的結合

如果項目中使用了SpringSecurity，需要做兩個配置來讓springdoc正常使用：

1.在SpringSecurity配置類中放行白名單："/v3/api-docs/**", "/swagger-ui/**"

2.在SpringDoc配置中增加對應內容，如下：

@Configurationpublic class SpringDocConfig {

 

    private static final String SECURITY_SCHEME_NAME = "BearerAuth";

 

    @Bean

    public OpenAPI managerOpenAPI() {

 

        return new OpenAPI()

                .info(new Info().title("Galaxy-Cluster-Manager後端介面文檔")

                        .description("提供給前端界面（portal）的介面文檔")

                        .version("v1.0.0")

                        .license(new License().name("galaxy 1.2.0").url("https://gitlab.ctyun.cn/hpc/galaxy-parent/-/tree/v1.2.0")))

                .externalDocs(new ExternalDocumentation()

                        .description("彈性高性能計算（CTHPC）")

                        .url("http://www.ctyun.cn"))

                //以下是針對SpringSecurity的設置，同時還有設置白名單

                .addSecurityItem(new SecurityRequirement().addList(SECURITY_SCHEME_NAME))

                .components(new Components()

                        .addSecuritySchemes(SECURITY_SCHEME_NAME,

                                new SecurityScheme()

                                        .name(SECURITY_SCHEME_NAME)

                                        .type(SecurityScheme.Type.HTTP)

                                        .scheme("bearer")

                                        .bearerFormat("JWT")));

    }

    @Bean

    public GroupedOpenApi publicApi() {

        return GroupedOpenApi.builder()

                .group("portal")

                .pathsToMatch("/api/**")

                .build();

    }

}

7.SpringDoc使用對象作為Query參數的問題

實際上springfox也會有這個問題，使用對象作為query傳參的時候，頁面通常是這樣的：

就沒有辦法逐個描述參數，也不能逐個調試（只能用json調試），非常的麻煩；springdoc有一個解決這個問題非常方便的註解：@ParameterObject

比如某一個控制器的入參是User user，我們只需要在這前面加上註解變為：@ParameterObject User user 即可，結果如下;

 

這裡也有一個大坑：參數的類型可能會不正確，比如這裡我們的id參數實際上是int，但顯示出來是string，這個時候就需要我們在User類的屬性中加上對應的註解，比如：

@Parameter(description = "id傳參",example = "6")

再重啟UI就會發現參數類型正確了

8.SpringDoc配置掃包範圍

有的時候僅僅使用@Hidden並不能滿足我們的需要，因為可能需要配置不同group的controller類，這個時候就需要在配置類中取設置掃包範圍代碼如下：

 

9.SpringDoc的優劣勢

優勢：SpringDoc有著非常好看的UI，以及比Springfox更加完善的參數註解體系，看起來非常舒服，並且還在不斷更新與維護中

劣勢：一些冷門功能還不完善，比如：

a.有十個介面，他們的url是一樣的但是可以通過query參數來分別（如：@PostMapping(params = "action=QueryUsers")）這個時候springdoc只能通過掃包範圍配置，來寫多個GroupOpenApi來解決，非常的麻煩；springfox可以在docket創建的時候使用：docket.enableUrlTemplating(true); 這個方法即可解決

b.springdoc的網路配置可能會與springfox衝突，如果遷移，需要逐個嘗試網路配置是否合適（主要是GsonHttpMessageConverter的配置）

c.相容性問題仍需要觀望，相對於springfox，springdoc的相容性並沒有那麼好，在許多時候可能會出現序列化的亂碼問題

 

總結：如果當前項目/工程已經集成了完備的springfox，建議不要輕易嘗試遷移到springdoc，尤其是介面類型比較複雜、springfox配置docket比較多的項目；但如果是從頭開始的項目，由於介面相對比較簡單，可以採用springdoc，畢竟可以獲得更加清晰明瞭的顯示界面與參數解釋。

 


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

-Advertisement-
Play Games
更多相關文章
  • Django筆記十七之group by 分組用法總結
    一個非常簡單的小項目。 看到了楊旭大佬的教學視頻，自己跟著實現了一下，完善了一下游戲邏輯。 通過空格鍵進行控制。 游戲中可按 P 鍵 暫停/恢復 游戲 項目結構 · ├── Cargo.lock ├── Cargo.toml ├── src/ │ ├── main.rs │ ├──bird/ │ │ ...
  • Spring源碼系列一：入門——Hello World
    本文介紹了學習Spring源碼前需要掌握的核心知識點，包括IOC、AOP、Bean生命周期、初始化和Transaction事務。通過Hello World示例，講解瞭如何使用Spring，並指出了深入瞭解Spring內部機制的方向。 ...
  • sync.Pool：提高Go語言程式性能的關鍵一步
    約束(Constraints) 上一章介紹了向模型中添加一些業務邏輯的能力。我們現在可以將按鈕鏈接到業務代碼，但如何防止用戶輸入錯誤的數據？例如，在我們的房地產模塊中，沒有什麼可以阻止用戶設置負預期價格。 odoo提供了兩種設置自動驗證恆定式的方法：Python約束 and SQL約束。 SQL 參 ...
  • MyBatis常見問題
    Mybatis常見問題 1，大於號、小於號在sql語句中的轉換 使用 mybatis 時 sql 語句是寫在 xml 文件中,如果 sql 中有一些特殊的字元的話,比如< ，<=，>，>=等符號，會引起 xml 格式的錯誤，需要替換掉，或者不被轉義。 有兩種方法可以解決：轉義字元和標記 CDATA ...
  • day05-SpringCloud Eureka-服務註冊與發現02
    SpringCloud Eureka-服務註冊與發現02 3.搭建EurekaServer集群-實現負載均衡&故障容錯 3.1為什麼需要集群EurekaServer？ 微服務RPC遠程服務調用最核心的是高可用 如果註冊中心只有1個，如果出現故障，會導致整個服務環境不可用 解決辦法就是搭建Eureka ...
  • java -- Math、BigInteger、BigDecimal類和基本類型的包裝類、正則表達式
    ps 命令速查備忘清單 Linux我們提供了一個名為 ps 的實用程式，用於查看與系統上的進程相關的信息，它是 Process Status 的縮寫這份 ps 命令備忘清單的快速參考列表，包含常用選項和示例。入門，為開發人員分享快速參考備忘單。 開發速查表大綱 入門 語法 示例 查看系統上的每個進程 ...
  • Perl語言線上代碼運行編譯工具推薦
    Perl語言線上運行編譯,是一款可線上編程編輯器,在編輯器上輸入Perl語言代碼,點擊運行,可線上編譯運行Perl語言,Perl語言代碼線上運行調試,Perl語言線上編譯,可快速線上測試您的Perl語言代碼,線上編譯Perl語言代碼發現是否存在錯誤,如果代碼測試通過，將會輸出編譯後的結果。 該線上工 ...
  • WAL模塊主要方法簡述
    簡介 ChatGPT Java版SDK開源地址：https://github.com/Grt1228/chatgpt-java ，目前收穫將近1000個star。 有bug歡迎朋友們指出，互相學習，所有咨詢全部免費。 最新版：1.0.10 <dependency> <groupId>com.unfb ...
一周排行
    -Advertisement-
    Play Games
  • 移動開發（一）：使用.NET MAUI開發第一個安卓APP
    移動開發（一）：使用.NET MAUI開發第一個安卓APP 對於工作多年的C#程式員來說，近來想嘗試開發一款安卓APP，考慮了很久最終選擇使用.NET MAUI這個微軟官方的框架來嘗試體驗開發安卓APP，畢竟是使用Visual Studio開發工具，使用起來也比較的順手，結合微軟官方的教程進行了安卓 ...
  • wpf ToggleButton選中效果和一個登錄界面
    前言 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 ...
  • 第27篇 sqlserver2022詳細安裝步驟
    話不多說，直接開乾 一.下載 1.官方鏈接下載： https://www.microsoft.com/zh-cn/sql-server/sql-server-downloads 2.在下載目錄中找到下麵這個小的安裝包 SQL2022-SSEI-Dev.exe，運行開始下載SQL server； 二. ...
  • .NET 開源高性能 MQTT 類庫
    前言 隨著物聯網（IoT）技術的迅猛發展，MQTT（消息隊列遙測傳輸）協議憑藉其輕量級和高效性，已成為眾多物聯網應用的首選通信標準。 MQTTnet 作為一個高性能的 .NET 開源庫，為 .NET 平臺上的 MQTT 客戶端與伺服器開發提供了強大的支持。 本文將全面介紹 MQTTnet 的核心功能 ...
  • Serilog文檔翻譯系列（六） - 可用的接收器、增強器、格式化輸出
    Serilog支持多種接收器用於日誌存儲，增強器用於添加屬性，LogContext管理動態屬性，支持多種輸出格式包括純文本、JSON及ExpressionTemplate。還提供了自定義格式化選項，適用於不同需求。 ...
  • 警惕 Visual Studio 屬性求值副作用導致邏輯不符合預期
    目錄簡介獲取 HTML 文檔解析 HTML 文檔測試參考文章 簡介 動態內容網站使用 JavaScript 腳本動態檢索和渲染數據，爬取信息時需要模擬瀏覽器行為，否則獲取到的源碼基本是空的。 本文使用的爬取步驟如下： 使用 Selenium 獲取渲染後的 HTML 文檔 使用 HtmlAgility ...
  • [使用目前最新版]HybridCLR6.9.0+YooAsset2.2.4實現純C# Unity熱更新方案 (一)
    1.前言 什麼是熱更新 游戲或者軟體更新時，無需重新下載客戶端進行安裝，而是在應用程式啟動的情況下，在內部進行資源或者代碼更新 Unity目前常用熱更新解決方案 HybridCLR，Xlua，ILRuntime等 Unity目前常用資源管理解決方案 AssetBundles，Addressable， ...
  • 在 ASP.NET Core Web API 中使用操作篩選器統一處理通用操作
    本文章主要是在C# ASP.NET Core Web API框架實現向手機發送驗證碼簡訊功能。這裡我選擇是一個互億無線簡訊驗證碼平臺，其實像阿裡雲，騰訊雲上面也可以。 首先我們先去 互億無線 https://www.ihuyi.com/api/sms.html 去註冊一個賬號 註冊完成賬號後，它會送 ...
  • 第28篇 如何.net中實現高效可靠數據同步api
    通過以下方式可以高效，並保證數據同步的可靠性 1.API設計 使用RESTful設計，確保API端點明確，並使用適當的HTTP方法（如POST用於創建，PUT用於更新）。 設計清晰的請求和響應模型，以確保客戶端能夠理解預期格式。 2.數據驗證 在伺服器端進行嚴格的數據驗證，確保接收到的數據符合預期格 ...
所有分類