03_Swagger2的使用与前后端协议
作者:互联网
文章目录
1. Swagger
1.1 Swagger介绍
前后端分离开发模式中,api文档是最好的沟通方式。
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务, 而前面发的PostMan更多的是前端开发人员使用, 并且Swagger使用会比PostMan体验感更好
主要功能只需要记住以下俩点:
- 生成在线接口文档
- 方便接口测试
1.2 使用步骤
- 导入依赖:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>3.0.0</version>
</dependency>
- 创建公共模块,在公共模块中创建子模块(common----service_base),在这个子模块中整合Swagger,即Swagger配置类:(也可以不创建模块,在包下直接整合)
import com.google.common.base.Predicates;
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.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;
@Configuration//配置类
@EnableSwagger2//注解开启Swagger2
public class SwaggerConfig {
@Bean
public Docket webApiConfig(){
//设置要配置的Swagger环境
Profiles profiles = Profiles.of("dev", "test");
//通过environment.acceptsProfiles判断是否处在自己设定的环境中
boolean flag = environment.acceptsProfiles(profiles);
return new Docket(DocumentationType.SWAGGER_2)
/**
* 配置API文档分组
* 随便写, 可以写你的项目名称
*/
.groupName("API")
.apiInfo(webApiInfo())
/**
* apis():指定扫描的接口
* RequestHandlerSelectors:配置要扫描接口的方式
* basePackage:指定要扫描的包
* any:扫面全部
* none:不扫描
* withClassAnnotation:扫描类上的注解(参数是类上注解的class对象)
* withMethodAnnotation:扫描方法上的注解(参数是方法上的注解的class对象)
*/
.apis(RequestHandlerSelectors.basePackage("com.plane"))
.select()
/**
* paths():过滤路径
* PathSelectors:配置过滤的路径
* any:过滤全部路径
* none:不过滤路径
* ant:过滤指定路径:按照按照Spring的AntPathMatcher提供的match方法进行匹配
* regex:过滤指定路径:按照String的matches方法进行匹配
*/
// .paths(Predicates.not(PathSelectors.regex("/admin/.*")))
.paths(Predicates.not(PathSelectors.regex("/error.*")))
.build();
}
private ApiInfo webApiInfo(){
return new ApiInfoBuilder()
.title("xxxx项目接口API文档")
.description("本文档描述了后端api微服务接口定义")
.version("1.0")
.build();
}
}
其中.select().apis.paths.build
是一套组合进行使用
-
如果创建了子模块, 在需要使用Swagger的模块中(例如service)需要引入公共模块依赖
-
启动主程序访问
localhost:8080/swagger-ui.html
进行测试
1.3 常用注解
我们可以在实体类上和其属性上添加注解来添加对应的注释
POJO:
@ApiModel
为类添加注释@ApiModelProperty
为类属性添加注释
controller:
- @Api:使用在类上
- @ApiOperation:使用在方法上
- @ApiParam:使用在参数上
2. 前后端协议
在前后端分离的项目中, 我们需要开发文档以便前端更好的调用后端接口(Swagger生成), 而我们后端主要的职责就是完成返回数据与操作数据
此时返回数据就需要我们与前端交流之后统一返回数据格式,使前端(iOS Android, Web)对数据的操作更一致、轻松, 否则前端使用Ajax接收Json数据之后数据就会很混乱, 这就是前后端协议, 也称之为统一返回数据格式
示例(构造器私有化, 提供静态方法进行链式编程返回):
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.util.HashMap;
import java.util.Map;
/**
* 统一返回类型
*/
@Data
public class R {
@ApiModelProperty(value = "是否成功")
private Boolean success;
@ApiModelProperty(value = "返回码")
private Integer code;
@ApiModelProperty(value = "返回消息")
private String message;
@ApiModelProperty(value = "返回数据")
private Map<String, Object> data = new HashMap<String, Object>();
//构造器私有化
private R() {
}
//成功静态方法
public static R ok() {
R r = new R();
r.setSuccess(true);
r.setCode(ResultCode.SUCCESS);
r.setMessage("成功");
return r;
}
//失败静态方法
public static R error() {
R r = new R();
r.setSuccess(false);
r.setCode(ResultCode.ERROR);
r.setMessage("失败");
return r;
}
public R success(Boolean success) {
this.setSuccess(success);
return this;
}
public R message(String message) {
this.setMessage(message);
return this;
}
public R code(Integer code) {
this.setCode(code);
return this;
}
public R data(String key, Object value) {
this.data.put(key, value);
return this;
}
public R data(Map<String, Object> map) {
this.setData(map);
return this;
}
}
接着可以使用接口或者final类或者枚举来定义返回的code的返回值(可以使用HTTP的响应状态码来定义):
public interface ResultCode {
public static Integer SUCCESS = 200;//成功
public static Integer SERVICE_ERROR = 500;//服务器内部异常
public static Integer CLIENT_ERROR = 405;//服务器内部异常
public static Integer REDIRCT = 302;//重定向
public static Integer NOT_FOUND = 404;//资源不存在
}
405:请求方式没有对应的doXxx方法(如请求方式是get,但是Servlet中没有doGet方法)
标签:03,Swagger,return,前后,Swagger2,Integer,import,springfox,public 来源: https://blog.csdn.net/qq_41781632/article/details/123192739