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