前言
Spring Boot 框架是目前非常流行的微服務框架，我們很多情況下使用它來提供 Rest API，而對于 Rest API 來說很重要的一部分內容就是檔案，Swagger 為我們提供了一套通過代碼和注解自動生成檔案的方法，這一點對于保證 API 檔案的及時性將有很大的幫助，本文將使用 Swagger 2 規范的 Springfox 實作來了解如何在 Spring Boot 專案中使用 Swagger，主要包含了如何使用 Swagger 自動生成檔案、使用 Swagger 檔案以及 Swagger 相關的一些高級配置和注解，
Swagger 簡介
Swagger 是一套基于 OpenAPI 規范構建的開源工具，可以幫助我們設計、構建、記錄以及使用 Rest API，Swagger 主要包含了以下三個部分：
-
Swagger Editor：基于瀏覽器的編輯器，我們可以使用它撰寫我們 OpenAPI 規范，
-
Swagger UI：它會將我們撰寫的 OpenAPI 規范呈現為互動式的 API 檔案，后文我將使用瀏覽器來查看并且操作我們的 Rest API，
-
Swagger Codegen：它可以通過為 OpenAPI（以前稱為 Swagger）規范定義的任何 API 生成服務器存根和客戶端 SDK 來簡化構建程序，
為什么要使用 Swagger
當下很多公司都采取前后端分離的開發模式，前端和后端的作業由不同的工程師完成，在這種開發模式下，維持一份及時更新且完整的 Rest API 檔案將會極大的提高我們的作業效率，傳統意義上的檔案都是后端開發人員手動撰寫的，相信大家也都知道這種方式很難保證檔案的及時性，這種檔案久而久之也就會失去其參考意義，反而還會加大我們的溝通成本，而 Swagger 給我們提供了一個全新的維護 API 檔案的方式，下面我們就來了解一下它的優點：
-
代碼變，檔案變，只需要少量的注解，Swagger 就可以根據代碼自動生成 API 檔案，很好的保證了檔案的時效性，
-
跨語言性，支持 40 多種語言，
-
Swagger UI 呈現出來的是一份可互動式的 API 檔案，我們可以直接在檔案頁面嘗試 API 的呼叫，省去了準備復雜的呼叫引數的程序，
-
還可以將檔案規范匯入相關的工具（例如 SoapUI）, 這些工具將會為我們自動地創建自動化測驗，
以上這些優點足以說明我們為什么要使用 Swagger 了，您是否已經對 Swagger 產生了濃厚的興趣了呢？下面我們就將一步一步地在 Spring Boot 專案中集成和使用 Swagger，讓我們從準備一個 Spring Boot 的 Web 專案開始吧，
SpringBoot整合Swagger2
-
首先創建一個基礎的SpringBoot web專案，您可以通過 Spring Initializr 頁面生成一個空的 Spring Boot 專案，或者通過idea創建一個SpringBoot專案
-
添加依賴
- Spring Boot 的 Web 依賴
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>
- 集成swagger2
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency>
- 集成Swagger UI
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
- Spring Boot 的 Web 依賴
-
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()); } ? }
- 撰寫一些簡單的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"; } }
- 驗證代碼-到這里我們已經成功集成Swagger2，然后啟動專案，輸入http://localhost:8080/swagger-ui.html，如果能出現下面界面，說明配置成功了，
- 未完待續，下章節講解Swagger的常用注解，
這篇文章是否幫助到你呢？掃描關注公眾號--【Madison龍少】，【Madison龍少】公眾號每天提供java干貨，干貨滿滿，
轉載請註明出處，本文鏈接：https://www.uj5u.com/houduan/150685.html
標籤：Java
上一篇：Java基本語法