SpringBoot中使用Swagger生成RestFul規範API文件
j簡單介紹Swagger的作用:
Swagger是為了描述一套標準的而且是和語言無關的REST API的規範。對於外部呼叫者來說,只需通過Swagger文件即可清楚Server端提供的服務,而不需去閱讀原始碼或介面文件說明。
官方網站為:http://swagger.io
中文網站:http://www.sosoapi.com
在spring boot專案中新增依賴:
<!-- Swagger依賴 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>
編寫Swagger配置類,這個配置類和spring boot的啟動類是同級的
新增Swagger配置類,Swagger會預設把所有Controller中的RequestMapping方法都生成API出來,實際上我們一般只需要標準介面的(像返回頁面的那種Controller方法我們並不需要),所有你可以按下面的方法來設定要生成API的方法的要求。
package com.tencent.springboot_swaggerdemo; 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 /** * 啟用swaggerapi */ @EnableSwagger2 public class Swagger2 { /** * basePackage可以指定生成api的包,指定的包下面的controller類中的requestMapping方法會生成api解釋 * @return */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.tencent.springboot_swaggerdemo.controller")) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot中使用Swagger2構建RESTful APIs") .description("更多Spring Boot相關文章請關注:http://www.baidu.com/") .termsOfServiceUrl("http://www.baidu.com/") .contact("程式猿DD") .version("1.0") .build(); } }
編寫controller中測試
package com.tencent.springboot_swaggerdemo.controller; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiOperation; import org.springframework.web.bind.annotation.PathVariable; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RestController; @RestController @Api(value = "HelloController",description = "使用者相關的api") public class HelloController { @RequestMapping(value = "/test/{name}",method = RequestMethod.GET) @ApiOperation(value = "測試swagger API",notes = "歡迎來測試") @ApiImplicitParam(name="name",value = "傳參名稱",required = true,dataType = "String") public String testAPI(@PathVariable String name){ return name; } }
我們啟動服務後,訪問:http://localhost:8080/swagger-ui.html 就完成了整合。
相關注解解讀
1. @Api
用在類上,說明該類的作用
@Api(value = "UserController", description = "使用者相關api")
2. @ApiOperation
用在方法上,說明方法的作用
@ApiOperation(value = "查詢使用者", notes = "查詢使用者", httpMethod = "GET", produces = MediaType.APPLICATION_JSON_UTF8_VALUE)
3 @ApiImplicitParams
用在方法上包含一組引數說明
4. @ApiImplicitParam
用在@ApiImplicitParams註解中,指定一個請求引數的各個方面
paramType:引數放在哪個地方
header–>請求引數的獲取:@RequestHeader
query–>請求引數的獲取:@RequestParam
path(用於restful介面)–>請求引數的獲取:@PathVariable
body(不常用)
form(不常用)
name:引數名
dataType:引數型別
required:引數是否必須傳
value:引數的意思
defaultValue:引數的預設值
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "唯一id", required = true, dataType = "Long", paramType = "path"),
})
5. @ApiResponses
用於表示一組響應
6. @ApiResponse
用在@ApiResponses中,一般用於表達一個錯誤的響應資訊
code:數字,例如400
message:資訊,例如”請求引數沒填好”
response:丟擲異常的類
@ApiResponses(value = {
@ApiResponse(code = 400, message = "No Name Provided")
})
7. @ApiModel
描述一個Model的資訊(這種一般用在post建立的時候,使用@RequestBody這樣的場景,請求引數無法使用@ApiImplicitParam註解進行描述的時候)
@ApiModel(value = "使用者實體類")
8. @ApiModelProperty
描述一個model的屬性
@ApiModelProperty(value = "登入使用者")
Swagger介面請求有幾個:
http://localhost:8080/swagger-resources/configuration/ui
http://localhost:8080/swagger-resources
http://localhost:8080/api-docs
http://localhost:8080/swagger-resources/configuration/security