Springboot整合Swagger2
1. 什么是Swagger
相信无论是前端还是后端开发，都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力，经常来不及更新。其实无论是前端调用后端，还是后端调用后端，都期望有一个好的接口文档。但是这个接口文档对于程序员来说，就跟注释一样，经常会抱怨别人写的代码没有写注释，然而自己写起代码起来，最讨厌的，也是写注释。所以仅仅只通过强制来规范大家是不够的，随着时间推移，版本迭代，接口文档往往很容易就跟不上代码了。
发现了痛点就要去找解决方案。解决方案用的人多了，就成了标准的规范，这就是Swagger的由来。通过这套规范，你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具，就可以做到生成各种格式的接口文档，生成多种语言的客户端和服务端的代码，以及在线接口调试页面等等。这样，如果按照新的开发模式，在开发新版本或者迭代版本的时候，只需要更新Swagger描述文件，就可以自动生成接口文档和客户端服务端代码，做到调用端代码、服务端代码以及接口文档的一致性。
但即便如此，对于许多开发来说，编写这个yml或json格式的描述文件，本身也是有一定负担的工作，特别是在后面持续迭代开发的时候，往往会忽略更新这个描述文件，直接更改代码。久而久之，这个描述文件也和实际项目渐行渐远，基于该描述文件生成的接口文档也失去了参考意义。所以作为Java届服务端的大一统框架Spring，迅速将Swagger规范纳入自身的标准，建立了Spring-swagger项目，后面改成了现在的Springfox。通过在项目中引入Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式，在后面需求持续迭代的项目中，显得尤为重要和高效。
2. Swagger注解详解
2.1 @Api可以标记一个 Controller 类作为 Swagger 文档资源
tags：接口说明，可以在页面中显示。可以配置多个，当配置多个的时候，在页面中会显示多个接口的信息。description:对tags 进行描述说明
@RequestMapping("/api") @Api(tags = "测试swagger接口",description = "User模块")//描述 复制代码
2.2 @ApiModel
@ApiModel 用在类上，表示对类进行说明，用于实体类中的参数接收说明
@Data @ApiModel(value = "com.pojo",description = "用户pojo") public class User { @ApiModelProperty(value = "账号") private String username; @ApiModelProperty(value = "密码") private String password; } 复制代码
2.3 @ApiModelProperty
@ApiModelProperty() 用于字段，表示对 model 属性的说明
package com.pojo; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; @Data @ApiModel(value = "com.pojo",description = "用户pojo") public class User { @ApiModelProperty(value = "账号") private String username; @ApiModelProperty(value = "密码") private String password; } 复制代码
2.4 @ApiParam
@ApiParam 用于 Controller 中方法的参数说明
- value：参数说明
- required：是否必填
@RestController @RequestMapping("/api") @Api(tags = "测试swagger接口",description = "User模块")//描述 public class SwaggerController { @ApiOperation(value = "我的第一个swagger接口") @PostMapping("/swagger") public User testUser(@ApiParam(value = "用户实体",required = true) @RequestBody User user, HttpServletRequest request){ System.out.println(request.getHeader("token")); return user; } } 复制代码
2.5 @ApiOperation
@ApiOperation 用在 Controller 里的方法上，说明方法的作用，每一个接口的定义
value：接口名称
@RestController @RequestMapping("/api") @Api(tags = "测试swagger接口",description = "User模块")//描述 public class SwaggerController { @ApiOperation(value = "我的第一个swagger接口") @PostMapping("/swagger") public User testUser(@ApiParam(value = "用户实体",required = true) @RequestBody User user, HttpServletRequest request){ System.out.println(request.getHeader("token")); return user; } } 复制代码
2.6 @ApiResponse 和 @ApiResponses
@ApiResponse 用于方法上，说明接口响应的一些信息；@ApiResponses 组装了多个 @ApiResponse
@GetMapping("/getUser") @ApiOperation(value = "获取用户信息接口") @ApiResponses({ @ApiResponse(code = 0, message = "相应成功", response = SysUser.class) }) public SysUser getUserInfo(@ApiParam(value = "用户id",required = true) @RequestParam String id){ return userService.getUserInfo(id); } 复制代码
2.7 @ApiImplicitParam 和 @ApiImplicitParams
用于方法上，为单独的请求参数进行说明
@GetMapping("/getUser") @ApiOperation(value = "获取用户信息接口") @ApiResponses({ @ApiResponse(code = 0, message = "相应成功", response = SysUser.class) }) @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用户id", dataType = "string", paramType = "query", required = true, defaultValue = "0f09e661-7e80-4e1b-b66a-2e266bb593bf") }) public SysUser getUserInfo(@ApiParam(value = "用户id",required = true) @RequestParam String id){ return userService.getUserInfo(id); } 复制代码
3. 引入Swagger的jar
<!--swagger2 依赖--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> </dependency> 复制代码
4. 创建Swagger的配置类
package com.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.ParameterBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.schema.ModelRef; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Parameter; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; import java.util.ArrayList; import java.util.List; @Configuration//表示这是一个配置类 @EnableSwagger2//开启Swagger2 public class SwaggerConfig { @Bean public Docket reeateDocket(){ List<Parameter> parameterList=new ArrayList<>(); ParameterBuilder parameterBuilder=new ParameterBuilder(); parameterBuilder.name("token") .description("swagger调试用，模拟传入用户凭证") .modelRef(new ModelRef("String")) .parameterType("header").required(false); parameterList.add(parameterBuilder.build()); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo())//创建该Api的基本信息（这些基本信息会展现在文档页面中） .select()//函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger ui来展现 .apis(RequestHandlerSelectors.basePackage("com.controller"))//指定需要扫描的包路路径 .paths(PathSelectors.any()) .build() .globalOperationParameters(parameterList) ; } //配置swagger的信息 private ApiInfo apiInfo(){ return new ApiInfoBuilder() .title("spring boot2.x实战") .description("整合swagger") .termsOfServiceUrl("") .version("2.0") .build(); } } 复制代码
5. 实体类创建
package com.pojo; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; @Data @ApiModel(value = "com.pojo",description = "用户pojo") public class User { @ApiModelProperty(value = "账号") private String username; @ApiModelProperty(value = "密码") private String password; } 复制代码
6. 测试类创建
package com.controller; import com.pojo.User; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.http.HttpRequest; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import javax.servlet.http.HttpServletRequest; @RestController @RequestMapping("/api") @Api(tags = "测试swagger接口",description = "User模块")//描述 public class SwaggerController { @ApiOperation(value = "我的第一个swagger接口") @PostMapping("/swagger") public User testUser(@ApiParam(value = "用户实体",required = true) @RequestBody User user, HttpServletRequest request){ System.out.println(request.getHeader("token")); return user; } } 复制代码
7. 测试
在浏览器上输入：http://localhost:8080/swagger-ui.html
