如何在 swgger 中设置连接前后端的 API 接口

在的网站大多都是前后端分离式的开发，前后端都衍生出了自己的框架。现在前后端交互的唯一方式就是 API 接口。

曾经前后端交互都需要后端人员手动编写 API 接口文档，规定路径、请求方式、返回类型，这样效率很低。

swagger 就是更好地书写 API 文档的框架。

二、swagger 介绍

swagger 可以根据后台接口自动生成可视化的 restful 风格的 API 文档，并可以进行 API 测试（发送各种请求，测试接口）

1、前端人员不用再去理解后端代码，后端人员也不用专门编写接口文档。2、swagger 直接自动生成可供测试、可视化的 API 文档，前端人员在不知道后端代码的情况下，也能根据 swagger 提供的 API 文档理解每个接口的作用，并可以测试接口是否能够正常使用。

三、在 maven+springboot 项目中使用 swagger

1.首先在 pom.xml 中导入依赖

 springfox-swagger2 是 swagger 的 java 实现 springfox-swagger-ui 是网页上显示 swagger 文档的 jar 包

   <dependency>       <groupId>io.springfox</groupId>       <artifactId>springfox-swagger2</artifactId>       <version>2.8.0</version>   </dependency>   <dependency>      <groupId>io.springfox</groupId>      <artifactId>springfox-swagger-ui</artifactId>      <version>2.8.0</version>   </dependency>复制代码

复制代码

2.编写 swagger 配置文件 

创建一个 config 文件夹，在文件夹里创建 SwaggerConfig.java 文件作为我们的 swagger 配置文件。

import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.ComponentScan;import org.springframework.context.annotation.Configuration;import org.springframework.web.servlet.config.annotation.EnableWebMvc;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; @Configuration // 标注一个配置类@EnableSwagger2 // 提供swagger注解@ComponentScan("whu.xsy.swagger_use.controller")//扫描控制器包下的文件public class SwaggerConfig {     @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .apiInfo(apiInfo());    }     //展现API文档的基本信息    private ApiInfo apiInfo(){    	//联系人信息(展现在主页)        Contact contact = new Contact("xsy",                "","827041735@qq.com");        return new ApiInfoBuilder()                .title("测试swagger")                .description("测试swagger对于接口的展示和调用")                .contact(contact)                .version("1.1.0")                .build();    }}复制代码

复制代码

1. 创建实体类 Student

import io.swagger.annotations.ApiModel;import io.swagger.annotations.ApiModelProperty; @ApiModel(value = "学生类")public class student {     @ApiModelProperty(value = "学号",required = true)    private int id;     @ApiModelProperty(value = "姓名")    private String name;     public student() {}     public student(int id, String name) {        this.id = id;        this.name = name;    }     public int getId() { return id; }     public void setId(int id) { this.id = id; }     public String getName() { return name; }     public void setName(String name) { this.name = name; }}复制代码

复制代码

4.创建控制器 studentController（此处用 List 模拟数据库）

import io.swagger.annotations.Api;import io.swagger.annotations.ApiImplicitParam;import io.swagger.annotations.ApiImplicitParams;import io.swagger.annotations.ApiOperation;import org.springframework.web.bind.annotation.*;import whu.xsy.swagger_use.entity.student; import java.util.ArrayList;import java.util.List;  @RestController@RequestMapping("/student")@Api(value = "studentController", tags = "学生模块") //标注在类上的public class studentController {     //模拟数据库    private static List students = new ArrayList<>();     //初始化模拟数据库    static{        students.add(new student(1,"xsy"));        students.add(new student(2,"theory"));    }     @ApiOperation(            value = "获取所有学生信息",            notes = "获取所有学生的学号和姓名"    )    @GetMapping("")    public List getAll(){        return students;    }       @ApiOperation(            value = "获取单个学生",            notes = "根据id查询学生，id为整数，返回学生实体，没查到则返回null"    )    @ApiImplicitParam(value = "学生学号", name = "id",paramType = "path")    @GetMapping("/{id}")    public student getById(@PathVariable("id") int id){        for (student s : students) {            if(s.getId() == id)                return s;        }        return null;    }       @ApiOperation(            value = "添加单个学生",            notes = "前端上传学生信息（学号，姓名）"    )    //此处 name 一定要与student中的变量名相同，否则在前端会生成新的parameter    @ApiImplicitParams({            @ApiImplicitParam(value = "学生学号",name = "id",paramType = "query"),            @ApiImplicitParam(value = "学生姓名",name = "name",paramType = "query")    })    @PostMapping("")    public boolean add(student student){        return students.add(student);    }       @ApiOperation(            value = "更新单个学生",            notes = "前端上传学生信息（学号，姓名），学号相同则会更新"    )    //此处 name 一定要与student中的变量名相同，否则在前端会生成新的parameter    @ApiImplicitParams({            @ApiImplicitParam(value = "学生学号",name = "id",paramType = "query"),            @ApiImplicitParam(value = "学生姓名",name = "name",paramType = "query")    })    @PutMapping("")    public boolean update(student student){        for (student s : students) {            if(s.getId() == student.getId()) {                students.set(students.indexOf(s), student);                return true;            }        }        return false;    }       @ApiOperation(            value = "删除单个学生",            notes = "根据学生id删除某个学生"    )    @ApiImplicitParam(value = "学生学号", name = "id",paramType = "path")    @DeleteMapping(value = "/{id}")    public boolean deleteById(@PathVariable("id") int id){        for (student s : students) {            if(s.getId() == id)                return students.remove(s);        }        return false;    }}复制代码

复制代码

1. 输入 localhost:8080/swagger-ui.html，打开 swagger-ui 界面

6. 查看并测试 API 接口 

进入 post 方法，parameters 展示了后台接收的参数，后面的描述对应 ApiImplicitParam 中的 value，点击 Try it out

输入参数值后点击 Execute 运行

然后就可以在下方查看到后台返回结果了 

1. 验证是否真的上传成功

同样的操作使用获取所有学生信息的 GET 接口，可以发现刚刚插入的 id 为 3，名字为 ys 的学生已经插入了

四、swagger 在项目中的好处

• 前后端可以只通过 swagger-ui.html 交互，前端完全不需要后台代码，只用看 API 文档就可以调用相应接口。

• 有时需要往数据库中插入测试数据，但是不建议直接操作数据库加入数据，直接在数据库中加入的时候有时会影响后台插入数据，而后台又需要写代码插入不同数据，非常麻烦，使用 swagger-ui 调用 post 方法，可视化地去添加数据，方便快捷。

• 及时更新。后台代码更新后，无需后台人员区更改 API 接口文档，swagger 直接同步了。