SpringBoot+Swagger2集成詳細說明

引言：

為什么使用Swagger？

在Vue沒有出來之前，都是前后端在一起：

• 后端用的SSM或者SSH框架

• 前端完全就是靜態頁面+模板引擎。例如：JSP開發久的人應該聽說過，和現在的Thymeleaf、 Velocity、FreeMarker 類似

在Vue出來之后，進入真正的前后端分離時代：

• 后端依然可以是SSM架構，而現在大廠都在使用微服務SpringBoot、SpringCloud等

• 前端就獨立出來了，只管呈現效果也就是是三層架構的視圖層

為什么叫前后端分離呢？

分離就是各自開發自己的，互不干擾

優點：

• 前端可以不用等后端人員開發完在測試，直接就可以使用Json偽造數據測試，例如：JsonServer工具

• 可以部署在不同的服務器上

• 有新的項目可以隨時拆分模塊

缺點：

• 此時就需要在招專業開發前端的人員，這就是老板的事了。。。

Swagger簡介：

Swagger是一個流行的API開發框架，Swagger容許用戶使用Swagger編輯器描述OAS 3.0API，并使用SwaggerUI可視化并自動生成OAS 3.0中定義的API文檔。

Swagger可以對整個API開發周期提供一個完整框架，解決調試過程中的各種問題，包括API設計，開發，測試，完檔，并且幾乎支持所有語言。

Swagger的用途來了：

問題：

前后端分離聯調，前后端人員無法做到及時的調試？

當年的解決方案：

• 編寫Word文檔，及時更新(但是很難做到，一般容易忘記)

• 模擬測試后端接口：postman

• 后端開發完之后，提供接口，根據需求在調整

現在的解決方案：

• Api文檔與API定義同步更新

• 直接運行，在線測試后端接口

• 對多種編程語言的支持

SpringBoot集成Swagger：

1.建立SpringBoot-Web項目

2.引入Swagger依賴

Swagger UI：用于展示API規范

Springfox：是一個通過掃描代碼提取代碼中的信息，生成API文檔的工具。API文檔的格式不止Swagger的OpenAPI Specification，還有RAML，jsonapi，Springfox的目標同樣包括支持這些格式。

?<dependency> ? ?<groupId>io.springfoxgroupId> ? ?<artifactId>springfox-swagger2artifactId> ? ?<version>2.9.2version>dependency><dependency> ? ?<groupId>io.springfoxgroupId> ? ?<artifactId>springfox-swagger-uiartifactId> ? ?<version>2.9.2version>dependency>

3.配置Swagger

?@Configuration@EnableSwagger2 // 開啟Swaggerpublic class SwaggerConfig {}

4.編寫Controller

?@RestControllerpublic class TestController { ? ?@RequestMapping("hello") ? ?public String hello(){ ? ? ? ?return "hello swagger2"; ? }}

6.項目結構

7.啟動項目

訪問：http://localhost:8080/swagger-ui.html

Swagger配置進階

Swagger信息和組信息進行配置

?@Configuration@EnableSwagger2 // 開啟Swaggerpublic class SwaggerConfig {// ? 配置Docket的bean實例 ? ?@Bean ? ?public Docket docket(Environment environment){ ? ? ? ?return new Docket(DocumentationType.SWAGGER_2) ? ? ? ? ? ? ? .apiInfo(apiInfo()) ? ? ? ? ? ? ? .enable(true)// enable是否啟動Swagger，如果False，則Swagger不能再瀏覽器中訪問 ? ? ? ? ? ? ? .groupName("yangjun")// 配置API分組 ? ? ? ? ? ? ? .select()// ? ? ? ? ? ? ? RequestHandlerSelectors，配置掃描接口的方式// ? ? ? ? ? ? ? basePackage：指定要掃描的包// ? ? ? ? ? ? ? any()：掃描全部// ? ? ? ? ? ? ? none()：不掃描// ? ? ? ? ? ? ? withClassAnnotation：掃描類上的注解，參數是一個注解的反射對象// ? ? ? ? ? ? ? withMethodAnnotation：掃描方法上的注解 ? ? ? ? ? ? ? .apis(RequestHandlerSelectors.basePackage("com.example.controller"))// ? ? ? ? ? ? ? paths 過濾路徑 ? ? ? ? ? ? ? ?//.path(PathSelectors.ant("/example/**")) ? ? ? ? ? ? ? .build(); ? }// ? 配置Swagger信息=apiInfo ? ?private ApiInfo apiInfo() {// ? ? 作者信息 ? ? ? ?Contact contact = new Contact("作者：XX","作者QQ空間","作者Email"); ? ? ? ?return new ApiInfo("測試SwaggerApi文檔" ? ? ? ,"好好學習，天天向上", ? ? ? ? ? ? ? ?"V0.1", ? ? ? ? ? ? ? ?"團隊文檔地址", ? ? ? ? ? ? ? ?contact, ? ? ? ? ? ? ? ?"Apache2.0", ? ? ? ? ? ? ? ?"Apache2.0地址", ? ? ? ? ? ? ? ?new ArrayList<>()); ? }}

問題來了：

如果我們只在測試環境中使用，而不在生產環境中使用該怎么辦？

?enable(true)// enable是否啟動Swagger，如果False，則Swagger不能再瀏覽器中訪問

• 判斷當前的環境

• 設置enable(true)值

?public Docket docket(Environment environment){ ? ?//設置要顯示的Swagger環境 ? ?Profiles profiles = Profiles.of("dev","test"); ? ?//通過environment.acceptsProfiles判斷是否處在自己設定的環境當中 ? ?boolean flag = environment.acceptsProfiles(profiles); ? ?return new Docket(DocumentationType.SWAGGER_2) ? ? ? .apiInfo(apiInfo()) ? ? ? .enable(flag)// enable是否啟動Swagger，如果False，則Swagger不能再瀏覽器中訪問 ? ? ? .groupName("yangjun")// 配置API分組 ? ? ? .select() ? ? ? .apis(RequestHandlerSelectors.basePackage("com.example.controller")) ? ? ? .build();}

配置分組

配置多個實例即可

?@Beanpublic Docket docket1(){return new Docket(DocumentationType.SWAGGER_2).groupName("測試分組1");}@Beanpublic Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName("測試分組2");}

API使用：

涉及到的5個注解

• @Api(tags = "類")：加在類上

• @ApiOperation：加在方法上

• @ApiParam("用戶名")：加在參數上

• @ApiModel("用戶實體類")：加在實體類上

• @ApiModelProperty("用戶名")：加在字段上

1.@Api的使用

在類上使用主要來闡述這個類的作用

?@Api(tags = "TestController測試類")@RestControllerpublic class TestController { ? ?@RequestMapping(value = "/hello",method = RequestMethod.GET) ? ?public String hello(){ ? ? ? ?return "hello swagger2"; ? }}

2.@ApiOperation的使用

在方法上使用主要來闡述這方法的用戶以及需要傳入那些參數和類型

?@Api(tags = "TestController測試類")@RestControllerpublic class TestController { ? ?@RequestMapping(value = "/hello",method = RequestMethod.GET) ? ?public String hello(){ ? ? ? ?return "hello swagger2"; ? } ? ?@ApiOperation("測試控制類1") ? ?@PostMapping("/user1") ? ?public String getUser2(@ApiParam("用戶名") User user){ ? ? ? ?return user.toString(); ? }}

3.@ApiParam的使用

定義用戶輸入參數的格式，不用在拼接字符串，Swagger會自動配置好，我們只要填入參數測試

?@Api(tags = "TestController測試類")@RestControllerpublic class TestController { ? ?@RequestMapping(value = "/hello",method = RequestMethod.GET) ? ?public String hello(){ ? ? ? ?return "hello swagger2"; ? } ? ?@ApiOperation("測試控制類1") ? ?@PostMapping("/user1") ? ?public String getUser2(@ApiParam("用戶名") User user){ ? ? ? ?return user.toString(); ? }}

4.@ApiModel和@ApiModelProperty的使用

在實體類使用，提供每個字段名和類型，關鍵可以和MybatisPlus一起使用，只要在數據庫中定義好字段的備注，使用MP的代碼自動生成就OK了

?@Data@ApiModel("用戶實體類")public class User { ? ?@ApiModelProperty("用戶名") ? ?private String name; ? ?@ApiModelProperty("用戶密碼") ? ?private String password;}

總結：

1.在開發過程中對接口更新更快

2.能夠快速導出API文檔

3.不用第三方工具即可測試接口

完整代碼：

https://gitee.com/hahaguai007/springboot-swagger2.git

點亮 ，告訴大家你也在看

總結

以上是生活随笔為你收集整理的freemarker使用说明_SpringBoot+Swagger2集成详细说明的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。