03_Swagger2的使用与前后端协议

2023-10-09 13:19:04

文章目录

1. Swagger
2. 前后端协议

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方法)

码农公寓