Swagger在Spring Rest API中的使用

2021-01-07 NewCloud

編寫了Spring rest apis後，與前端開發人員共享，以便他們可以與之集成。前端開發人員將需要所有其餘的api端點以及每個端點的請求方法，請求參數，請求正文和響應格式。

你將如何分享有關您的api的所有信息？手動記錄所有api是非常困難和耗時的。

此外，如果您手動記錄api，則每次在api中進行一些更改時都必須更改文檔。

好！如果我告訴你，你可以使用一個名為Swagger的神奇工具自動化所有這些東西怎麼辦？

什麼是Swagger？

Swagger是世界上最流行的API框架，支持40多種不同的語言。您可以使用swagger來設計，構建和記錄您的其他api。

在這篇文章中，我們將學習如何使用Swagger來記錄用java和Spring框架編寫的rest apis。

Swagger使用非常少的集成代碼為您的所有其他api創建一個漂亮的交互式文檔。

所以，讓我們將Swagger與Spring結合起來，為我們的休息時間賦予生命。

將Swagger與Spring集成

1.添加Swagger依賴項

Swagger規範由Springfox的java庫實現。

我們需要添加Springfox依賴項來將Swagger與Spring集成。我們將使用Springfox的Swagger 2依賴項來獲取Swagger的最新功能。

如果使用maven，請將以下依賴項添加到pom.xml文件中

如果gradle是您選擇的構建系統，那麼您可以將以下依賴項添加到build.gradle文件中 -

2. Swagger配置

我通常SwaggerConfig.java在config我的應用程式包中創建一個文件，並在此文件中寫入所有Swagger配置 -

該@EnableSwagger2註解被用於使能應用Swagger 2的支持。

所有配置都是通過DocketBean 完成的。你可以給出一個標題，並使用apiInfo配置為你的api寫一個很好的描述。

此外，您可以通過選擇paths與謂詞匹配的內容來決定在文檔中包含哪個api 。

上面的配置足以在Spring啟動應用程式中集成Swagger。您現在可以運行應用程式並轉到/swagger-ui.html端點以訪問swagger文檔。

這就是將Swagger集成到Spring Boot項目中的簡單方法。但是，對於非spring-boot項目，我們需要很少的額外集成代碼。

非Spring Boot的配置

如果您未在項目中使用Spring啟動，則/swagger-ui.html端點將給出404 not found錯誤，因為沒有為此端點配置資源處理程序。

當您將Swagger與Spring引導集成時，它會自動為您配置所有資源處理程序。但是對於Spring，你必須自己做。

幸運的是，這並不難。只需使用以下內容在項目包WebMvcConfig.java內創建一個文件config-

如果你已經擴展WebMvcConfigurerAdapter了項目的某個配置類，那麼只需添加上面的資源處理程序，你就可以了。

這就是讓Swagger在非Spring啟動項目中工作所需要做的一切。請通過/swagger-ui.html在瀏覽器中打開端點來驗證它。

結論

Swagger非常有助於自動記錄您的apis。我幾乎在所有項目中都使用它。在這篇文章中我們將swagger與非常基本的配置集成在一起，但Springfox在記錄你的apis方面提供了很多東西。

相關焦點

  • SwaggerSpringBootStarter 2.1.1 版本更新發布
    對於spring boot的web項目，可以添加這個依賴方便地進行swagger的api 接口展示，不需要對代碼進行任何修改，只需要添加依賴即可，甚至配置文件的配置也是可選的，可以添加到開發的包的構建配置中，那樣就不會對正式包產生任何影響。
  • Spring Doc 生成OPEN API 3文檔
    Maven 依賴要整合springdoc-openapi 和 Swagger UI ， 唯一要做的就是添加springdoc-openapi-ui依賴到項目pom.xml文件中。swagger-ui4. springdoc-openapi 與Spring WebFlux集成我們可以在Spring WebFlux 項目中通過添加依賴：springdoc-openapi-webflux-ui與spri
  • Spring Boot集成Swagger實例(maven版)
    •@ApiIgnore：使用該註解忽略這個API。•@ApiError：發生錯誤返回的信息。•@ApiParamImplicitL：一個請求參數。•@ApiParamsImplicit：多個請求參數2、準備工作2.1、準備相關依賴3、正式篇3.1、加入依賴<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId
  • 接口文檔從Swagger升級成knife4j使用教程
    Swagger應該是大部分Java程式設計師都有聽說過或者使用過，不過呢，我覺得Swagger的界面使用起來有太好用，聲明僅代表我的個人觀點。Knife4j是一個為Swagger接口文檔賦能的工具，提供了我認為更加良好的操作體驗。截止2020-11-02，版本已經升級到Knife4j 2.0.7了。
  • Spring Security接管Swagger認證授權,我發現僅用了3行關鍵代碼!
    ></dependency><dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId
  • 重磅:Swagger3.0官方starter誕生了,其它的都可以扔了~
    Swagger 是一套基於 OpenAPI 規範（OpenAPI Specification，OAS）構建的開源工具，可以幫助我們設計、構建、記錄以及使用 Rest API。OAS本身是一個API規範，它用於描述一整套API接口，包括一個接口是哪種請求方式、哪些參數、哪些header等，都會被包括在這個文件中。
  • 如何用 Go 快速編寫出 HTTP REST API 服務?
    Swagger安裝：請參考go-swagger安裝頁面（https://github.com/go-swagger/go-swagger/blob/master/docs/install.md）。然後，為了檢查該工具在你的系統中正確安裝，你可以檢查Swagger的版本。
  • 使用 Swagger 文檔化和定義 RESTful API
    舉例而言，通過使用 Swagger Editor，您可以創建或導入 API 文檔，並在一個交互式環境中瀏覽它。右側的顯示窗格顯示了格式化的文檔，反映了您在左側窗格中的代碼編輯器中執行的更改。代碼編輯器指出了所有格式錯誤。您可以展開和摺疊每個窗格。
  • 如何在 ASP.Net Core 中使用 Swagger - 51CTO.COM
    /v1/swagger.json", "v1");     }); 為了完整性，下面是 Startup 中的所有代碼清單。/v1/swagger.json", "v1");             });         }     } } 瀏覽 Swagger UI現在我們運行一下應用程式來瀏覽一下 Swagger UI 地址，可以看到 UI 界面如下圖所示，圖中不同的 Http 請求使用了不同的顏色進行標識，你甚至可以在UI上直接測試不同的 api
  • Salesforce Rest Api詳解一之Spring Boot集成
    該博客介紹了使用REST API與Salesforce集成的方法。我們將使用Spring Boot進行身份驗證（從Salesforce獲取access_token和instance_url）。儘管可以使用普通的Java應用程式來完成此操作，但是我們將假設現實中的用例需要Web應用程式來調用服務。
  • 使用 swagger 為 Gin 項目生成接口文檔
    swagger介紹Swagger本質上是一種用於描述使用JSON表示的RESTful API的接口描述語言。Swagger與一組開源軟體工具一起使用，以設計、構建、記錄和使用RESTful Web服務。Swagger包括自動文檔，代碼生成和測試用例生成。
  • Dubbo 版 Swagger 來啦!Dubbo-Api-Docs 發布
    >如果 dubbo 提供者的接口和方法參數在一個單獨的 jar 項目中，則在該項目中引入: dubbo-api-docs-annotations。 該倉庫中包含了 Dubbo-Api-Docs 的文檔相關註解、註解掃描能力和使用示例：dubbo-api-docs-annotations：文檔生成的相關註解。考慮到實際情況中 dubbo api 的接口類和接口參數會規劃為一個單獨的 jar 包，所以註解也獨立為一個 jar 包。本文後面會對註解做詳細說明。
  • Swagger天天用,背後原理來一次深度解析
    springfox-swagger 是基於 Spring 生態系統的該規範的實現。springfox-swagger-ui 是對 swagger-ui 的封裝，使得其可以使用 Spring 的服務。由於工作中遇到需要基於 Swagger Json 做一些處理，但 Swagger Json 的格式不是那麼滿足需求。
  • REST API URI 設計 7 準則
    在他的「Web架構公理」列表中列出了關於 URI 的不透明度的注釋：唯一可以使用標識符的是對對象的引用。例如：http://api.xxx.com/shapes/polygons/quadrilaterals/squares規則＃3：應使用連字符（ - ）來提高 URI 的可讀性為了使你的 URI 容易被人檢索和解釋，請使用連字符（ - ）來提高長路徑段中名稱的可讀性。在任何你將使用英文的空格或連字號的地方，在URI中都應該使用連字符來替換。
  • Swagger天天用,但它背後的實現原理很多人都不知道!
    springfox-swagger 是基於 Spring 生態系統的該規範的實現。springfox-swagger-ui 是對 swagger-ui 的封裝，使得其可以使用 Spring 的服務。由於工作中遇到需要基於 Swagger Json 做一些處理，但 Swagger Json 的格式不是那麼滿足需求。
  • OpenAPI Generator v4.1.1 發布,OpenAPI 規範自動生成代碼
    4.1.1 版本已經發布，更新內容如下：General [core]設置 isMultiPart=true 用於多部分操作，修復 NPE 在服務中使用 anyof/oneof 時，修復導入和屬性名稱 自動更新生成腳本：userdef cache dir 修復了從 allVars 中丟失的組合屬性
  • 「語言實踐」Go語言文檔自動化之go-swagger
    1 go-swagger依賴包獲取go-swagger中在github的倉庫下的依賴包如下，主要包含可以對語法進行校驗的govalidator，文檔化的標準specification的go-openapi，還有網絡處理的golang.org官網旗下的net和text。
  • 快速創建 Spring Cloud 應用的 Spring Initializr 使用及原理
    相信很多人都使用過 start.spring.io 來初始化自己的 Spring Boot 工程，這個工具為開發者提供了豐富的可選組件，並且可以選擇多種打包方式，大大方便了開發人員的使用。最近，阿里的 Nacos、Sentinel 也進入 start.spring.io 的選項中，進一步的方便開發者使用阿里雲的產品。
  • 使用pyhttptest 輕鬆測試 REST API
    現在，我們每個人都面臨著 REST API，要麼開發這樣的服務，要麼使用這樣的服務。 此外，我們正處於微服務的時尚時代，我們將業務邏輯分割成獨立於每個服務的小型獨立服務。 這些服務大多遵循 RESTful 原則，並使用 JSON 格式進行通信，由於其簡單性，JSON 格式成為最廣泛使用的格式。
  • Spring Boot Swagger2自動生成接口文檔和Mock模擬數據
    接下來一起來看看怎麼在項目中集成Swagger和Easy Mock吧。2.1 添加依賴配置pom.xml，添加如下代碼：其中：springfox-swagger2 用於JSON API文檔的生成；springfox-swagger-ui