swagger使用与介绍
swagger是什么?
Swagger 是一个规范且完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。通俗的讲,Swagger 就是将项目中所有接口(想要暴露出去的接口)展现在页面上,并且可以进行接口调用和测试的服务。
为什么使用swagger?
1、后端程序员就不需要专门为前端使用者编写专门的接口文档;
2、当接口更新之后,只需要修改代码中的 Swagger 描述就可以实时生成新的接口文档了;
3、可以直接进行接口调用,降低了项目开发阶段的调试成本。
springboot集成swagger
1.引入pom
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
2.swagger2的配置文件
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.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
//swagger2的配置文件
@Configuration
@EnableSwagger2
public class SwaggerConfig {// swagger2的配置文件,这里可以配置swagger2的一些基本的内容,比如扫描的包等等
@Value("${swagger.enable}")
private boolean enable;//是否开启swagger
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("springboot.hello.helloSpringboot.demo"))// 为当前包路径
.paths(PathSelectors.any())
.build()
.apiInfo(apiInfo())
.enable(enable);
}
// 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
// 页面标题
.title("Spring Boot 演示使用 Swagger2 构建RESTful API")
// 创建人信息
.contact(new Contact("name", "url", "邮箱"))
// 版本号
.version("1.0")
// 描述
.description("API 描述")
.build();
}
}
yml增加
#是否激活 swagger true or false
swagger.enable=true
3.注解
3.1注解说明
用于controller类上:
@Api:对请求类的说明
用于方法上面(说明参数的含义):
@ApiOperation:方法的说明
@ApiImplicitParams、@ApiImplicitParam:
方法的参数的说明;@ApiImplicitParams 用于指定单个参数的说明
用于方法上面(返回参数或对象的说明):
@ApiResponses、@ApiResponse:方法返回值的说明 ;@ApiResponses:用于指定单个参数的说明
对象类:
@ApiModel:用在JavaBean类上,说明JavaBean的 用途
@ApiModelProperty:用在JavaBean类的属性上面,说明此属性的的含议
3.2注解属性说明
3.2.1.@Api:请求类的说明
@Api:放在 请求的类上,与 @Controller 并列,说明类的作用,如用户模块,订单类等。
tags="说明该类的作用"
value="该参数没什么意义,所以不需要配置"
示例:
@Api(tags="订单模块")
@Controller
public class OrderController {
}
@Api 其它属性配置:
属性名称 | 备注 |
---|---|
value | url的路径值 |
tags | 如果设置这个值、value的值会被覆盖 |
description | 对api资源的描述 |
basePath | 基本路径 |
position | 如果配置多个Api 想改变显示的顺序位置 |
produces | 如, “application/json, application/xml” |
consumes | 如, “application/json, application/xml” |
protocols | 协议类型,如: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
hidden | 配置为true ,将在文档中隐藏 |
3.2.2.@ApiOperation:方法的说明
@ApiOperation:"用在请求的方法上,说明方法的作用"
value="说明方法的作用"
notes="方法的备注说明"
3.2.2.1@ApiImplicitParams、@ApiImplicitParam:方法参数的说明
@ApiImplicitParams:用在请求的方法上,包含一组参数说明
@ApiImplicitParam:对单个参数的说明
name:参数名
value:参数的说明、描述
required:参数是否必须必填
paramType:参数放在哪个地方
· query --> 请求参数的获取:@RequestParam
· header --> 请求参数的获取:@RequestHeader
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(请求体)--> @RequestBody User user
· form(普通表单提交)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
示例:
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation(value="用户登录",notes="随边说点啥")
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public JsonResult login(@RequestParam String mobile, @RequestParam String password,
@RequestParam Integer age){
//...
return JsonResult.ok(map);
}
}
3.2.3.@ApiResponses、@ApiResponse:方法返回值的状态码说明
@ApiResponses:方法返回对象的说明
@ApiResponse:每个参数的说明
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
示例:
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation("获取用户信息")
@ApiImplicitParams({
@ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id")
})
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功"),
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
@ResponseBody
@RequestMapping("/list")
public JsonResult list(@RequestParam String userId) {
...
return JsonResult.ok().put("page", pageUtil);
}
}
3.2.4.@ApiModel:用于JavaBean上面,表示对JavaBean 的功能描述
@ApiModel的用途有2个:
当请求数据描述,即 @RequestBody 时, 用于封装请求(包括数据的各种校验)数据;
当响应值是对象时,即 @ResponseBody 时,用于返回值对象的描述。
示例:
@ApiModel(description = "用户登录")
public class UserLoginVO implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "用户名",required=true)
private String username;
@ApiModelProperty(value = "密码",required=true)
private String password;
// getter/setter省略
}
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation(value = "用户登录", notes = "")
@PostMapping(value = "/login")
public R login(@RequestBody UserLoginVO userLoginVO) {
User user=userSerivce.login(userLoginVO);
return R.okData(user);
}
}
3.2.5.@ApiModelProperty:用在JavaBean类的属性上面,说明属性的含义
示例:
@ApiModel(description= "返回响应数据")
public class RestMessage implements Serializable{
@ApiModelProperty(value = "是否成功",required=true)
private boolean success=true;
@ApiModelProperty(value = "错误码")
private Integer errCode;
@ApiModelProperty(value = "提示信息")
private String message;
@ApiModelProperty(value = "数据")
private Object data;
/* getter/setter 略*/
}
4.注解使用
4.1Controller代码
@ApiOperation(value = "post请求调用示例", notes = "接口说明", response = String.class)
@ApiResponses(value = {@ApiResponse(code = 200,message = "请求成功",response = String.class),@ApiResponse(code = 500,message = "内部异常",response = String.class)})
@RequestMapping(value = "/invokePost",method = {RequestMethod.POST})
public FFResponseModel<DemoOutputDto> invokePost(@ApiParam(name="传入对象",value="传入json格式",required=true) @RequestBody @Valid DemoDto input) {
return new FFResponseModel(200, "返回成功",new DemoOutputDto());
}
4.2接口请求入参对象
@Data
@ApiModel(value="演示类",description="请求参数类" )
public class DemoDto implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "defaultStr",example="mockStrValue")
private String strDemo;
@ApiModelProperty(example="1234343523",required = true)
private Long longNum;
@ApiModelProperty(example="111111.111")
private Double doubleNum;
@ApiModelProperty(example="2018-12-04T13:46:56.711Z")
private Date date;
}
4.3接口请求出参公共类
@ApiModel(value="基础返回类",description="基础返回类")
public class FFResponseModel<T> implements Serializable {
private static final long serialVersionUID = -2215304260629038881L;
// 状态码
@ApiModelProperty(example="成功")
private String code;
// 业务提示语
@ApiModelProperty(example="000000")
private String msg;
// 数据对象
private T data;
}
4.4接口请求出参实际数据对象
@Data
public class DemoOutputDto {
private String res;
@ApiModelProperty(value = "defaultOutputStr",example="mockOutputStrValue")
private String outputStrDemo;
@ApiModelProperty(example="6666666",required = true)
private Long outputLongNum;
@ApiModelProperty(example="88888.888")
private Double outputDoubleNum;
@ApiModelProperty(example="2018-12-12T11:11:11.111Z")
private Date outputDate;
}