Spring Boot中如何使用Swagger詳解
Swagger 簡介
Swagger 是一個方便 API 開發的框架,它有以下優點:
- 自動生成在線文檔,後端開發人員的改動可以立即反映到在線文檔,並且不用單獨編寫接口文檔,減輕瞭開發負擔
- 支持通過 Swagger 頁面直接調試接口,方便前端開發人員進行測試
配置 Swagger
Swagger 目前有 2.x 和 3.x 兩個主流版本,配置略有不同。
添加依賴
首先去 Maven 倉庫中搜索 springfox 查找依賴的坐標,Swagger 是遵循 OpenAPI 規范的技術,而 springfox 是該技術的一種實現,所以這裡要搜 springfox 而不是 swagger。
對於 Swagger 2.x,需要在 pom.xml 中添加兩項配置:
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency>
對於 Swagger 3.x,簡化瞭配置項,隻需要在 pom.xml 中添加一項配置:
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>
為項目開啟 Swagger
對於 Swagger 2.x,使用 @EnableSwagger2 註解開啟 Swagger 功能。
@EnableSwagger2 @SpringBootApplication public class SwaggerApplication { ... }
對於 Swagger 3.x,使用 @EnableOpenApi 註解開啟 Swagger 功能。
@EnableOpenApi @SpringBootApplication public class SwaggerApplication { ... }
創建 SwaggerConfig 配置類
- 對於 Swagger 2.x,實例化 Docket 的時候,需要傳入 DocumentationType.SWAGGER_2。
- 對於 Swagger 3.x,實例化 Docket 的時候,需要傳入 DocumentationType.OAS_30。
下面是一份配置模板:
import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.*; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; @Configuration public class SwaggerConfig { @Value("${spring.profiles.active:NA}") private String active; @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) // OAS_30 .enable("dev".equals(active)) // 僅在開發環境開啟Swagger .apiInfo(apiInfo()) .host("http://www.example.com") // Base URL .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("API文檔") .description("這是描述信息") .contact(new Contact("張三", null, null)) .version("1.0") .build(); } }
訪問 Swagger 前端頁面
- 對於 Swagger 2.x,訪問 http://localhost:8080/swagger-ui.html
- 對於 Swagger 3.x,訪問 http://localhost:8080/swagger-ui/
控制器相關註解
@Api:將一個類標記為 Swagger 資源,一般放在 Controller 類上面,通過 tags 指定描述信息,比如 @Api(tags=”用戶管理”)。
@ApiOperation:本註解放在 Controller 方法上面,描述該方法的作用。
@ApiParam:本註解放在 Controller 方法的形參前面,可以描述參數的作用,比如 @ApiParam(“用戶名”) String username。可以使用 value 指定描述信息,通過 required = true 指定必需傳遞該參數。
package com.example.swagger.controller; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @Api(tags = "Hello控制器") @RestController public class HelloController { @ApiOperation("展示歡迎信息") @GetMapping("/hello") public String hello(@ApiParam("名字") String name) { return "hello, " + name; } }
實體相關註解
- @ApiModel:一般放在實體類上面。可以通過 value 指定別名,不指定時默認為類名。還可以通過 description 指定詳細的描述信息。比如 @ApiModel(“用戶”) 就將顯示 用戶 而不是 User。
![](cdn.jsdelivr.net/gh/jpch89/P… 在 Spring Boot 中使用 Swagger 00.png)
如果僅僅想指定描述,而不改變原始類名顯示,可以寫成 @ApiModel(description = “用戶”)。
- @ApiModelProperty:一般放在實體類的成員變量上面,通過 value 指定描述信息,example 指定示例數據,required = true 指定該參數是必需的,hidden = true 用於隱藏該字段,不會在 API 文檔中顯示。
package com.example.swagger.pojo; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; @Data @ApiModel(description = "用戶") public class User { @ApiModelProperty("用戶名") private String username; @ApiModelProperty("密碼") private String password; @ApiModelProperty(value = "年齡", example = "18", required = true) private int age; @ApiModelProperty(hidden = true) private double money; }
總結
到此這篇關於Spring Boot中如何使用Swagger的文章就介紹到這瞭,更多相關SpringBoot使用Swagger內容請搜索WalkonNet以前的文章或繼續瀏覽下面的相關文章希望大傢以後多多支持WalkonNet!
推薦閱讀:
- 手把手教你SpringBoot快速集成Swagger的配置過程
- SpringBoot集成Swagger3的實現
- springboot詳解整合swagger方案
- swagger @ApiModel添加實體類不生效的解決
- 關於springboot集成swagger及knife4j的增強問題