四、spring boot 2.x 整合 swagger
阿新 • • 發佈:2018-12-17
1、引入swagger maven依賴
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.8.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.8.0</version> </dependency>
2、編寫swagger配置類:Swagger2Config.java
package com.ldy.bootv2.demo; 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.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 public class Swagger2Config { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() .apis(RequestHandlerSelectors.basePackage("com.ldy.bootv2.demo.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder().title("Restful API") .description("swagger Restful API文件") .version("1.1.0").build(); } }
3、編寫測試介面:HelloController.java
package com.ldy.bootv2.demo.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; @RestController @Api(tags = "測試介面-API") public class HelloController { @GetMapping("/hello") @ApiOperation("hello的測試介面") @ApiImplicitParam(name = "name", value = "名稱", required = true, dataType = "String") public String index(@RequestParam(required = true) final String name) { return "hello " + name; } @PostMapping("/sum") @ApiOperation("兩整數求和介面") @ApiImplicitParams({ @ApiImplicitParam(name = "a", value = "引數a", required = true, dataType = "int"), @ApiImplicitParam(name = "b", value = "引數b", required = true, dataType = "int") }) public String sum(@RequestParam(required = true) final Integer a, @RequestParam(required = true) final Integer b) { int sum = a + b; return "a + b = " + sum; } }
5、點選“測試介面-API”展開介面列表
6、 測試介面:點選指定的介面,然後點選 “Tty it out”
7、測試介面:輸入引數
8、測試介面:點選下方的“Execute”按鈕提交請求,執行結果如下
9、swagger2常用註解說明
1、@Api:用在請求的類上,表示對類的說明
tags="說明該類的作用,可以在UI介面上看到的註解"
value="該引數沒什麼意義,在UI介面上也看到,所以不需要配置"
2、@ApiOperation:用在請求的方法上,說明方法的用途、作用
value="說明方法的用途、作用"
notes="方法的備註說明"
3、@ApiImplicitParams:用在請求的方法上,表示一組引數說明
@ApiImplicitParam:用在@ApiImplicitParams註解中,或者單獨用在只有一個引數的方法上,指定具體某一個請求引數的詳細資訊
name:引數名
value:引數的漢字說明、解釋
required:引數是否必須傳
paramType:引數放在哪個地方
· header --> 請求引數的獲取:@RequestHeader
· query --> 請求引數的獲取:@RequestParam
· path(用於restful介面)--> 請求引數的獲取:@PathVariable
· body(不常用)
· form(不常用)
dataType:引數型別,預設String,其它值dataType="Integer" defaultValue:引數的預設值
4、@ApiModel:用於響應類上,表示一個返回響應資料的資訊 (這種一般用在post建立的時候,使用@RequestBody這樣的場景, 請求引數無法使用@ApiImplicitParam註解進行描述的時候
@ApiModelProperty:用在屬性上,描述響應類的屬性
5、@ApiIgnore:使用該註解忽略這個API