Swagger规范 - RESTful风格的Web服务 - 前后端分离

一、什么是swagger

Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。大白话:前后端分离

  • 前生Spring-swagger
  • 今世Springfox

二、使用swagger规范搭建项目

1.maven导入swagger依赖

方式①:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

方式②(推荐):

<!-- swagger规范 -->
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.0.RELEASE</version>
</dependency>

Maven仓库:https://mvnrepository.com/artifact/com.spring4all/swagger-spring-boot-starter/1.9.0.RELEASE

2.创建swagger配置类

/**
 * @Author zqc
 * @Date 2020/11/12-13:42
 * @Description Swagger2配置类
 */
@Configuration
@EnableSwagger2
public class Swagger2Config {

    /**
     * yml配置文件添加
     * #是否激活 swagger 默认true
     * swagger:
     *   enabled: false
     */
    @Value("${swagger.enabled}")
    private boolean enableSwagger;

    /**
     * @return 创建Docket的Bean对象
     */
    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
		.enable(enableSwagger)      //设置swagger是否启用
                .select()   // 选择那些路径和api会生成document
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))    //对带有RestController注解的api进行监控
//                .apis(RequestHandlerSelectors.any())    // 对所有api进行监控
//                .apis(RequestHandlerSelectors.basePackage("com.example.Controller.DemoController"))   //对指定包下的api进行监控
                //不显示错误的接口地址
                .paths(Predicates.not(PathSelectors.regex("/error.*"))) //错误路径不监控
                .paths(PathSelectors.regex("/.*"))  // 对根下所有路径进行监控
                .build();
    }

    /**
     * @return 创建ApiInfo的基本信息
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("利用swagger2构建的API文档")
                .description("用restful风格写接口")
                .termsOfServiceUrl("http://localhost:8080/swagger-ui.html")
                .version("1.0")
                .build();
    }

}

3.控制层添加相关注解

/**
 * @Author zqc
 * @Date 2020/11/12-13:34
 * @Description 控制层
 */
@Api(tags = "swagger测试控制层...")
@RestController
@RequestMapping("/demo")
public class DemoController {

    @ApiOperation("默认适用所有请求方式,可用method参数指定Get请求方式...")
    @RequestMapping(method = RequestMethod.GET)
    public String helloRequestMethodGet() {
        return "Hello RequestMethod Get";
    }

    @ApiOperation("默认适用所有请求方式,可用method参数指定Post请求方式...")
    @RequestMapping(method = RequestMethod.POST)
    public String helloRequestMethodPost() {
        return "Hello RequestMethod Post";
    }

    @ApiOperation("Get请求,@PathVariable获得请求URL中的动态参数...")
    @GetMapping("/helloGet/{id}")
    public String helloGet(@PathVariable String id) {
        return "Hello Get"+id;
    }

    @ApiOperation("Post请求,@RequestParam将指定的请求参数赋值给方法中的形参...")
    @PostMapping("/helloPost")
    public String helloPost(@RequestParam("password") String password,
                            @RequestParam(value = "loginName",required = false,defaultValue = "admin") String loginName) {
        return "value-name属性的别名,require-指示参数是否绑定,defaultValue-无传参则使用默认值";
    }

    /**
     * 创建接收前端数据的临时实体类,也可写成一个 po 类
     * @Data :使用lombok-不用写get/set方法等等
     * maven添加依赖:
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.16.10</version>
        </dependency>
     *
     * @RequestBody :能接收到前端数据的关键
     */
    @Data
    private static class LoadingModel{
        @ApiModelProperty("ID")
        private String id;
        @ApiModelProperty("字段1")
        private String firstSegment;
        @ApiModelProperty("字段2")
        private String secondSegment;
    }
    @ApiOperation("循环录入数据...")
    @PostMapping("/updateData")
    public void updateSecondPoolInfo(@RequestBody List<LoadingModel> loadingModels){
        for(LoadingModel loadingModel : loadingModels){
            //遍历对每一个loadingModel进行相关业务操作
        }
    }

}

4.运行

本地访问链接(在原访问链接后加上swagger-ui.html): http://localhost:8080/swagger-ui.html

在这里插入图片描述

5.BUG

记录一下第一次写前后端分离开发时遇到的一些坑,需求原型类似下图,有多个时段(项目实际是一天24个时段),多个数据要求录入。

  • 后端思路:创建一个List来承接数据,然后遍历,根据id来录入每个对象数据,代码如上 updateData 请求,创建临时实体类来承接数据,使用 @RequestBody 来接收前端传递给后端的json字符串中的数据的(请求体中的数据的)。
  • 前端踩坑:swagger请求正常,但前端使用表单提交会报400错误,使用json格式提交还是会报400错误,这里代码若按如上编写,默认不带任何格式,可在前端打印数据格式对应查看。注意数据的传递格式。

在这里插入图片描述

相关注解的讲解可参考:https://www.jianshu.com/p/a0caf58b3653

end
  • 作者:suoyue_zhan(联系作者)
  • 发表时间:2020-11-24 05:03:09
  • 版权声明:自由转载-非商用-非衍生-保持署名(创意共享3.0许可证)
  • 转载声明:如果是转载栈主转载的文章,请附上原文链接
  • 公众号转载:请在文末添加作者公众号二维码(公众号二维码见右边,欢迎关注)
  • 评论