SpringBoot3整合SpringDoc實現線上介面文檔

来源:https://www.cnblogs.com/xiezhr/p/18253311
-Advertisement-
Play Games

寫在前面 在現目前項目開發中,一般都是前後端分離項目。前端小姐姐負責開發前端,苦逼的我們負責後端開發 事實是一個人全乾,在這過程中編寫介面文檔就顯得尤為重要了。然而作為一個程式員,最怕的莫過於自己寫文檔和別人不寫文檔 大家都不想寫文檔,那這活就交給今天的主角Swagger來實現了 一、專業名詞介紹 ...


寫在前面

在現目前項目開發中,一般都是前後端分離項目。前端小姐姐負責開發前端,苦逼的我們負責後端開發

事實是一個人全乾,在這過程中編寫介面文檔就顯得尤為重要了。然而作為一個程式員,最怕的莫過於自己寫文檔和別人不寫文檔

大家都不想寫文檔,那這活就交給今天的主角Swagger來實現了

一、專業名詞介紹

OpenApi是什麼?

解答:OpenApi是一個用於描述、定義和共用 RESTful API 文檔的規範。最新規範是 OpenAPI 3.0

Swagger是什麼?

解答: Swagger 是一個用於設計和測試 RESTful APIs 的工具。

它提供了API 描述、請求和響應示例、API 測試和文檔生成等豐富的功能。最新版本是Swagger3,支持OpenAPI3.0規範

SpringFox 是什麼?

SpringFox 是 Spring 社區維護的一個項目(非官方),幫助使用者將 Swagger 2 集成到 Spring 中。

目前國內項目使用的都是它

github地址:https://github.com/springfox/springfox

springDoc是什麼?

解答: Spring-doc也是 Spring 社區維護的一個項目(非官方),幫助使用者將 Swagger 3 集成到 Spring 中

SpringDoc 支持 Swagger 頁面 Oauth2 登錄,相較於 SpringFox 而言,它的支撐時間更長,無疑是更好的選擇

但是在國內發展較慢,網上一找資料,出來的基本上是 Swagger2的內容。

地址:https://springdoc.org/

OpenAPISpring-docSwagger 之間的關係

解答:OpenAPI 定義了一種標準的格式來表示 API 文檔,而 Swagger 是一個實現 OpenAPI 規範的工具

二、Swagger詳細簡介

Swagger 江湖人稱“絲襪哥”,是一個幫助程式員生成介面文檔的利器。

只需要簡單配置,就可以生成帶有漂亮UI界面的介面文檔,而且編寫的介面代碼變了

介面文檔隨之也跟著變,做到了真正的解放雙手。

官網https://swagger.io/

Swagger 優點

  • 號稱世界上最流行的API框架
  • Restful Api 文檔線上自動生成器
  • 直接運行,支持線上測試API
  • 不僅僅支持Java,還支持多種語言(如:PHPPythonNode.js等)

三、小試牛刀

說了這麼多Swagger 的優點,接下來就小試牛刀,看看怎麼將Swagger集成到SpringBoot中。

3.1、環境介紹

  • JDK:17
  • SpringBoot:3.3.0
  • Springdoc

註: 細心的小伙伴可能已經發現了,在springboot3.0之前我用的都是Springfox來集成Swagger管理我們的API介面文檔,

但是Springfox已經停止更新了,我們使用的是SpringBoot3 +jdk17 的環境後,Spring官網推薦了Springdoc 來整合swagger

3.2 新建一個springboot-web項目

3.3 添加依賴

由於篇幅原因,其他web項目相關依賴這裡就不一一貼出來了。

第一個依賴是必須的,而且版本必須大於2.0.0

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.2.0</version>
</dependency>

註:

我們這裡使用的是jdk17+springboot3.3.0 環境,原來swaggerV2V3都不能用了,小伙伴們一定更要註意這兒

不能引入的依賴

如果引入上面錯誤的依賴,項目啟動會報下麵錯誤,這時候我們引入上面正確的依賴重新啟動項目即可

報錯信息

3.4 編寫HelloController

新建一個controller包--->建立一個HelloController

新建Hellocontroller

@RestController
public class HelloController {

    @RequestMapping("/hello")
    public String hello(){
        return "hello";
    }
}

我們在瀏覽器中輸入“http://localhost:8080/hello” 後回車,出現如下界面,說明我們的hello開發成功了

hello介面正常訪問

3.5 訪問swagger介面頁面

:我們這裡採用的是openapi ,所以就不用像swaggerV2v3那樣添加配置類了

瀏覽器直接輸入:http://localhost:8080/swagger-ui/index.html 回車即可看到下麵界面

介面信息

整合swagger是不是很簡單呢

四、修改介面

多種請求方式

從上面截圖中我們看到,我們在HelloController 中只定義了一個介面,但是前端UI界面中出來個7種請求方式(GETPUTPOSTDELETEOPTIONSHEADPATCH)的介面,這是為什麼呢?

解答:@RequestMapping("/hello") 我們介面中只是指定了訪問地址,並沒有指定請求方式

我們將註解修改成@RequestMapping(path = "/hello",method = RequestMethod.GET)

或者@GetMapping("/hello") 然後重啟服務,我們看到界面上就只有一種請求方式的介面了

get請求方式

五、介面文檔常用配置

5.1 配置訪問路徑

application.yml中可以自定義api-docsswagger-ui的訪問路徑。當然了,如果沒配置,預設就是下麵路徑

springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    path: /swagger-ui.html

5.2 配置介面文檔基本信息

① 配置介面基本信息

新建一個config包--->併在包下建立一個SpringDocConfig配置類

新建配置類

② 配置介面文檔基礎信息

我們在配置類中添加如下代碼,

@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                // 配置介面文檔基本信息
                .info(this.getApiInfo())
                ;
    }

    private Info getApiInfo() {
        return new Info()
                 // 配置文檔標題
                .title("SpringBoot3集成Swagger3")
                // 配置文檔描述
                .description("SpringBoot3集成Swagger3示例文檔")
                // 配置作者信息
                .contact(new Contact().name("程式員小凡").url("https://www.xiezhrspace.cn").email("[email protected]"))
                // 配置License許可證信息
                .license(new License().name("Apache 2.0").url("https://www.xiezhrspace.cn"))
                // 概述信息
                .summary("SpringBoot3集成Swagger3示例文檔aaa")
                .termsOfService("https://www.xiezhrspace.cn")
                // 配置版本號
                .version("2.0");
    }

}

前端頁面訪問介面文檔頁面後顯示如下

介面基本信息

② 配置介面servers信息

介面可能存在多環境,如開發環境、測試環境、生產環境等

我們可以通過@OpenAPIDefinition 配合servers 屬性來配置不同環境,具體配置示例如下

@OpenAPIDefinition(
        servers = {
                @Server(description = "開發環境伺服器", url = "http://localhost:8080"),
                @Server(description = "測試環境伺服器", url = "https://test.xiezhr.com")
        }
)
@Configuration
public class SpringDocConfig {
    //...
}

配置完成後,瀏覽器訪問顯示如下

配置servers信息

③ 配置外部文檔信息

有時候我們需要在線上介面文檔中可以顯示跳轉到API的一些外部文檔(比如 項目部署文檔等)

這個時候我們可以通過@OpenAPIDefinition 配合 externalDocs 屬性來配置外部文檔

具體配置如下

@OpenAPIDefinition(

    externalDocs = @ExternalDocumentation(
        description = "項目編譯部署說明",
        url = "http://localhost:8080/deplay/readme.md"
    )
)
@Configuration
public class SpringDocConfig {
    //......
}

配置完後重啟服務,瀏覽器訪問介面文檔,顯示如下

外部API文檔

SpringDocConfig 類完整配置代碼如下

@OpenAPIDefinition(

        servers = {
                @Server(description = "開發環境伺服器", url = "http://localhost:8080"),
                @Server(description = "測試環境伺服器", url = "https://test.xiezhr.com")
        },
        externalDocs = @ExternalDocumentation(
                description = "項目編譯部署說明",
                url = "http://localhost:8080/deplay/readme.md"
        )
)

@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                // 配置介面文檔基本信息
                .info(this.getApiInfo())
                ;
    }

    private Info getApiInfo() {
        return new Info()
                 // 配置文檔標題
                .title("SpringBoot3集成Swagger3")
                // 配置文檔描述
                .description("SpringBoot3集成Swagger3示例文檔")
                // 配置作者信息
                .contact(new Contact().name("程式員小凡").url("https://www.xiezhrspace.cn").email("[email protected]"))
                // 配置License許可證信息
                .license(new License().name("Apache 2.0").url("https://www.xiezhrspace.cn"))
                //
                .summary("SpringBoot3集成Swagger3示例文檔aaa")
                .termsOfService("https://www.xiezhrspace.cn")

                // 配置版本號
                .version("2.0");
    }

  

}

配置完上面信息後,重啟服務,瀏覽器訪問:http://localhost:8080/v3/swagger-ui/index.html

介面文檔基本信息

5.3 配置掃描介面

應用場景:

有時候我們為了業務需要,我們建立了多個包下的介面,如admin包下的,common包下的介面,

為了安全起見,我們只允許介面文檔中訪問comm包下麵的介面。

在不加任何配置的情況下,所以介面都會預設顯示,具體如下

顯示所有介面

配置掃描介面包:

application.yml中可以自定義要掃描的介面包

springdoc:
  packages-to-scan: com.xiezhr.swaggerdemo.common.controller

配置好之後重啟服務,我們發現前臺UI只顯示了common包下麵的介面了

只顯示common包下麵的介面

5.4 配置介面文檔開關

使用場景:

為了介面安全,我們一般需要在測試(test)環境或者開發(dev)環境中開啟介面文檔,而在生產(prod)環境中 關閉介面文檔

這個應該怎麼做呢?

這裡涉及到SpringBoot多環境配置,忘記的小伙伴可以翻一翻之前的文章。傳送門:

我們創建三個配置文件,分別為

  • application-dev.yml 開發環境

  • application-test.yml 測試環境

  • application-prod.yml 生產環境

只需在①和②配置文件中添加如下配置

springdoc:
  api-docs:
    enabled: true

而③配置文件中添加

springdoc:
  api-docs:
    enabled: false

通過上面配置後,我們在開發和測試環境下:就能正常訪問http://localhost:8080/v3/swagger-ui/index.html#/

而在生產環境下就無法訪問,報如下錯誤

生產環境

5.5 配置API分組

為了演示API分組,我們在controller包下麵再建立admin包和common包,包下分別添加AdminControllerCommonController介面類,結構及代碼如下

包結構

AdminController

// AdminController
@RestController
@RequestMapping("/admin")
public class AdminController {

    @GetMapping("/index")
    public String  admin(){
        return "admin";
    }
}

CommonController

@RestController
@RequestMapping("/common")
public class CommonController {

   @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
}

在預設情況(沒有分組)的情況下,所有包下介面都顯示在一一個預設組下麵,如/common/* 和/admin/* 訪問路徑下的介面都顯示在一起,如下圖所示

預設分組

這時,如果/common/* 下的介面比較多,/admin/* 下的介面也比較多,界面上顯示就很混亂

解決辦法就是添加分組信息,我們在SpringDocConfig 配置類中添加如下代碼,這樣就把介面分為了"common通用模塊組" 和"admin模塊組" 兩個組

@Bean("commonGroupApi")
public GroupedOpenApi webGroupApi() {
    return GroupedOpenApi.builder().group("common通用模塊組")
        .pathsToMatch("/common/**")
        .build();
}

@Bean("adminGroupApi")
public GroupedOpenApi adminGroupApi() {
    return GroupedOpenApi.builder().group("admin模塊組")
        .pathsToMatch("/admin/**")
        .build();
}

重啟服務,再訪問http://localhost:8080/v3/swagger-ui/index.html 如下

API分組

5.6 配置介面信息

@Tag 註解使用

對一個 operation 進行說明或定義的標簽,用在類或方法上,也可以用在 @OpenAPIDefinition 中定義標簽。

常用參數:

  • name: 名稱
  • description: 介面描述信息

示例:

用在類上

@RestController
@RequestMapping("/common")
@Tag(name = "公共介面", description = "公共介面")
public class CommonController {
    //......
}

@Operation 註解使用

用於說明方法用途,用在方法上。

參數:

  • summary:方法概要,方法的一個簡單介紹,建議 120 個字元內
  • description:方法描述,一般是很長的內容
  • hidden:是否隱藏

示例:

@GetMapping("/hello")
@Operation(summary = "hello介面", description = "hello介面描述" ,hidden = true)
public String hello(){
    return "hello";
}

@Parameter註解使用

用於說明方法參數,用在方法參數上。

參數:

  • name:指定的參數名
  • in:參數位置,可選 queryheaderpathcookie,預設為空,表示忽略
  • description:參數描述
  • required:是否必填,預設為 false

示例:

@GetMapping("/user/{id}")
public User getUser( @Parameter(name = "id",in = ParameterIn.PATH,description = "用戶ID",required = true) @PathVariable("id") Integer id){
    User user = userService.getUserById(id);
    return user;
}

前端頁面查看

@Paramter註解配置信息

@ApiResponse 註解使用

用於說明一個響應信息,用在 @ApiResponses 中。

參數:

  • responseCode:HTTP 響應碼
  • description:描述

示例:

@GetMapping("/user/{id}")
@Operation(summary = "獲取用戶信息", description = "根據用戶ID獲取用戶信息")
@ApiResponses(value ={
    @ApiResponse(responseCode = "200", description = "請求成功"),
    @ApiResponse(responseCode = "404", description = "用戶不存在")            
})
public User getUser( @Parameter(name = "id",in = ParameterIn.PATH,description = "用戶ID",required = true) @PathVariable("id") Integer id){
    User user = userService.getUserById(id);
    return user;
}

@ApiResponse註解配置信息

完整配置

@RestController
@RequestMapping("/common")
@Tag(name = "公共介面", description = "公共介面")
public class CommonController {

    @Autowired
    private IUserService userService;

   @GetMapping("/hello")
   @Operation(summary = "hello介面", description = "hello介面描述" ,hidden = true)
    public String hello(){
        return "hello";
    }

    @GetMapping("/hi")

    @Operation(summary = "hi介面", description = "hi介面描述")
    public String Hi(){
        return "Hi 程式員小凡";
    }

    @GetMapping("/user/{id}")
    @Operation(summary = "獲取用戶信息", description = "根據用戶ID獲取用戶信息")
    @ApiResponses(value ={
            @ApiResponse(responseCode = "200", description = "請求成功"),
            @ApiResponse(responseCode = "404", description = "用戶不存在")
    })
    public User getUser( @Parameter(name = "id",in = ParameterIn.PATH,description = "用戶ID",required = true) @PathVariable("id") Integer id){
        User user = userService.getUserById(id);
        return user;
    }
}

重啟後,瀏覽器訪問http://localhost:8080/v3/swagger-ui/index.html 如下

image-20240615213336423

5.7 配置實體信息

① 新建一個User實體類

@Data
public class User {
    private String name;
    private Integer age;
    private String email;
    private String address;
}

@Schema標簽使用

用於描述數據對象信息或數據對象屬性,比如各種POJO類及屬性,用在類或類屬性上。

參數:

  • name:屬性名稱
  • description:屬性描述
  • required:是否必須
  • minLength:字元最小長度
  • maxLength:字元最大長度

③使用示例:

@Data
@Schema(description = "用戶實體類",name = "User")
public class User {
    @Schema(description = "用戶名",name =  "name",minLength =  6,maxLength = 20,required = true)
    private String name;
    @Schema(description = "年齡",name =  "age",required = true,minimum = "1",maximum = "100")
    private Integer age;
    @Schema(description = "郵箱",name =  "email",required = true)
    private String email;
    @Schema(description = "地址",name =  "address")
    private String address;
}

④ 瀏覽器訪問:http://localhost:8080/v3/swagger-ui/index.html ,我們看到配置的實體信息顯示出來了

實體信息

六、介面調試

通過上面各種配置之後,我們的線上介面文檔基本上生成得差不多了。接下來我們就來說說怎麼使用線上介面文檔進行介面測試

① 測試說明

在之前小節中我們開發了要給根據用戶ID 獲取用戶信息的介面getUser。我們現在要做的就是在前端UI界面中找到這個介面,

在開發環境下輸入用戶ID值,然後獲取用戶信息。

② 選擇組信息

【獲取用戶信息】這個介面在,common通用模塊組下麵,所以我們第一步就要前端UI界面右上角選擇這個組

選擇common通用模塊組

② 選擇開發環境

Servers 下選擇配置好的開發環境

選擇開發環境

找到我們要測試的介面

找到目標介面

④ 測試介面,獲取響應數據

介面右邊下三角箭頭展開介面------>點擊Try it out

點擊Try it out

輸入參數:用戶ID------> 點擊【Execute】----->在Response body 中查看介面響應信息

根據用戶id獲取到響應信息

七、添加請求頭

很多時候我們介面都需要認證之後才能訪問,這時候我們就需要介面調用的時候攜帶著Token信息

示例:

我們通過@RequestHeader 註解 獲取請求頭中token信息

@GetMapping("/index")
public String  admin(@RequestHeader ("token") String token){
	System.out.println("token>>>>>>>>>>>>>>>>>>>>>>>>"+token);
    //token 驗證
    //.....各種業務邏輯
    return "admin";
}

添加請求頭信息

到此,本期內容就結束了,★,°:.☆( ̄▽ ̄)/$:.°★ 。 希望對您有所幫助

我們下期再見 ヾ(•ω•`)o (●'◡'●)

本文來自博客園,作者:xiezhr,轉載請註明原文鏈接:https://www.cnblogs.com/xiezhr/p/18253311


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

-Advertisement-
Play Games
更多相關文章
  • 這篇文章介紹瞭如何運用Tailwind CSS框架創建響應式網頁設計,涵蓋博客、電商網站及企業官網的佈局實例,包括頭部導航、內容區域、側邊欄、頁腳及輪播圖等組件的響應式實現。同時,探討了與JavaScript框架集成、CSS預處理器配合、設計工具應用以及伺服器端渲染的策略,並提供了性能優化、代碼組織... ...
  • 我們是袋鼠雲數棧 UED 團隊,致力於打造優秀的一站式數據中台產品。我們始終保持工匠精神,探索前端道路,為社區積累並傳播經驗價值。 本文作者:修能 這是一段平平無奇的 SQL 語法 SELECT id, sum(name) FROM student GROUP BY id ORDER BY id; ...
  • ‍ 寫在開頭 點贊 + 收藏 學會 前言 在這之前公司項目的文檔預覽的方式都是通過微軟線上預覽服務,但是微軟的線上服務有文件大小限制,想完整使用得花錢,一些圖片文件就通過組件庫antd實現,因為我們項目存在多種類型的文件,所以為了改善用戶的體驗,決定把文件預覽單獨弄一個拆出一個項 ...
  • 這篇文章介紹了Tailwind CSS框架的特點與優勢,包括其作為實用性的CSS框架如何通過預設的樣式類實現快速佈局和設計,以及如何在不犧牲響應式和自適應性的同時減少開發時間。此外,還提及了框架的可定製性,允許開發者輕鬆創建符合項目需求的樣式規則,從而提高前端開發效率。 ...
  • Chrome 在 121 版本開始,原生支持了兩個滾動條樣式相關的樣式 scrollbar-color 和 scrollbar-width。 要知道,在此前,雖然有 ::-webkit-scrollbar 規範可以控制滾動條,可是,::-webkit-scrollbar 是非標準特性,在 MDN 文 ...
  • Spring Cloud是一個相對比較成熟的微服務框架。雖然,Spring Cloud於2016年才推出1.0的release版本, 時間最短, 但是相比Dubbo等RPC框架, Spring Cloud提供的全套的分散式系統解決方案。 Spring Cloud是一系列框架的有序集合。它利用Spri ...
  • Windows應用軟體開發,會有很多常用的模塊,比如資料庫、配置文件、日誌、後臺通信、進程通信、埋點、瀏覽器等等。下麵是目前我們公司windows梳理的部分組件,梳理出來方便大家瞭解組件概念以及依賴關係: 每個應用里,現在或者以後都可能會存在這些模塊。以我團隊開發的全家桶為例,十多個應用對後臺訪問, ...
  • 通過本文我們深入瞭解了RabbitMQ的集群模式及其優缺點。無論是普通集群還是鏡像集群,都有其適用的場景和局限性。普通集群利用Erlang語言的集群能力,但消息可靠性和高可用性方面存在一定挑戰;而鏡像集群通過主動消息同步提高了消息的可靠性和高可用性,但可能會占用大量網路帶寬。因此,在選擇集群方案時,... ...
一周排行
    -Advertisement-
    Play Games
  • 前言 本文介紹一款使用 C# 與 WPF 開發的音頻播放器,其界面簡潔大方,操作體驗流暢。該播放器支持多種音頻格式(如 MP4、WMA、OGG、FLAC 等),並具備標記、實時歌詞顯示等功能。 另外,還支持換膚及多語言(中英文)切換。核心音頻處理採用 FFmpeg 組件,獲得了廣泛認可,目前 Git ...
  • OAuth2.0授權驗證-gitee授權碼模式 本文主要介紹如何筆者自己是如何使用gitee提供的OAuth2.0協議完成授權驗證並登錄到自己的系統,完整模式如圖 1、創建應用 打開gitee個人中心->第三方應用->創建應用 創建應用後在我的應用界面,查看已創建應用的Client ID和Clien ...
  • 解決了這個問題:《winForm下,fastReport.net 從.net framework 升級到.net5遇到的錯誤“Operation is not supported on this platform.”》 本文內容轉載自:https://www.fcnsoft.com/Home/Sho ...
  • 國內文章 WPF 從裸 Win 32 的 WM_Pointer 消息獲取觸摸點繪製筆跡 https://www.cnblogs.com/lindexi/p/18390983 本文將告訴大家如何在 WPF 裡面,接收裸 Win 32 的 WM_Pointer 消息,從消息裡面獲取觸摸點信息,使用觸摸點 ...
  • 前言 給大家推薦一個專為新零售快消行業打造了一套高效的進銷存管理系統。 系統不僅具備強大的庫存管理功能,還集成了高性能的輕量級 POS 解決方案,確保頁面載入速度極快,提供良好的用戶體驗。 項目介紹 Dorisoy.POS 是一款基於 .NET 7 和 Angular 4 開發的新零售快消進銷存管理 ...
  • ABP CLI常用的代碼分享 一、確保環境配置正確 安裝.NET CLI: ABP CLI是基於.NET Core或.NET 5/6/7等更高版本構建的,因此首先需要在你的開發環境中安裝.NET CLI。這可以通過訪問Microsoft官網下載並安裝相應版本的.NET SDK來實現。 安裝ABP ...
  • 問題 問題是這樣的:第三方的webapi,需要先調用登陸介面獲取Cookie,訪問其它介面時攜帶Cookie信息。 但使用HttpClient類調用登陸介面,返回的Headers中沒有找到Cookie信息。 分析 首先,使用Postman測試該登陸介面,正常返回Cookie信息,說明是HttpCli ...
  • 國內文章 關於.NET在中國為什麼工資低的分析 https://www.cnblogs.com/thinkingmore/p/18406244 .NET在中國開發者的薪資偏低,主要因市場需求、技術棧選擇和企業文化等因素所致。歷史上,.NET曾因微軟的閉源策略發展受限,儘管後來推出了跨平臺的.NET ...
  • 在WPF開發應用中,動畫不僅可以引起用戶的註意與興趣,而且還使軟體更加便於使用。前面幾篇文章講解了畫筆(Brush),形狀(Shape),幾何圖形(Geometry),變換(Transform)等相關內容,今天繼續講解動畫相關內容和知識點,僅供學習分享使用,如有不足之處,還請指正。 ...
  • 什麼是委托? 委托可以說是把一個方法代入另一個方法執行,相當於指向函數的指針;事件就相當於保存委托的數組; 1.實例化委托的方式: 方式1:通過new創建實例: public delegate void ShowDelegate(); 或者 public delegate string ShowDe ...