参考链接:5分钟学会swagger配置

参考视频:Swagger-前后端分离开发的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包

		<!--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>
<!--swagger jar包-->
  1. 编写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
注解 作用
@ApiModel 标注在实体类上,value=类名描述
@ApiModelProperty 标注在属性上,value=字段描述,required默认为false,如果是不可缺少的字段,比如主键,required则要变成true

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; }
}
  1. 创建控制器studentController(此处用List模拟数据库)
注解 作用
@Api 标注在类上,tags则为类的名字,会展示给前端
@ApiOperation 标注在方法上,value简单地概括方法的用处,notes则描述方法的使用
@ApiImplicitParam 标注在方法上,用于描述参数字段,name是参数的名字(一定要与@Requestparam、@PathVariable、或者传递的类中的字段名相同,否则会在前端显示新的参数),required默认为false,如果是不可缺少的字段,则要改为true
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<student> students = new ArrayList<>(); //初始化模拟数据库
static{
students.add(new student(1,"xsy"));
students.add(new student(2,"theory"));
} @ApiOperation(
value = "获取所有学生信息",
notes = "获取所有学生的学号和姓名"
)
@GetMapping("")
public List<student> 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界面

  2. 查看并测试API接口

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



输入参数值后点击Execute运行



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

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

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

四、swagger在项目中的好处

  • 前后端可以只通过swagger-ui.html交互,前端完全不需要后台代码,只用看API文档就可以调用相应接口。
  • 有时需要往数据库中插入测试数据,但是不建议直接操作数据库加入数据,直接在数据库中加入的时候有时会影响后台插入数据,而后台又需要写代码插入不同数据,非常麻烦,使用swagger-ui调用post方法,可视化地去添加数据,方便快捷。
  • 及时更新。后台代码更新后,无需后台人员区更改API接口文档,swagger直接同步了。

五、美化界面

有时候swagger界面比较难以操作,特别是需要不断切换接口时,点击起来比较麻烦,而且很多人不喜欢swagger界面的样式,这里提供一个用bootstrap渲染的swagger界面

  1. pom.xml加入依赖
        <dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.6</version>
</dependency>
  1. 打开localhost:8080/doc.html,界面变成下面这样



swagger -- 前后端分离的API接口的更多相关文章

  1. 前后端分离后台api接口框架探索

    前言 很久没写文章了,今天有时间,把自己一直以来想说的,写出来,算是一种总结吧!  这篇文章主要说前后端分离模式下(也包括app开发),自己对后台框架和与前端交互的一些理解和看法.     前后端分离 ...

  2. 前后端分离后API交互如何保证数据安全性

    前后端分离后API交互如何保证数据安全性? 一.前言 前后端分离的开发方式,我们以接口为标准来进行推动,定义好接口,各自开发自己的功能,最后进行联调整合.无论是开发原生的APP还是webapp还是PC ...

  3. Swagger - 前后端分离后的契约

    前后端分离 按照现在的趋势,前后端分离几乎已经是业界对开发和部署方式所达成的一种共识.所谓的前后端分离,并不是传统行业中的按部门划分,一部分人只做前端(HTML/CSS/JavaScript等等),另 ...

  4. 如何处理好前后端分离的 API 问题(转载自知乎)

    9 个月前 API 都搞不好,还怎么当程序员?如果 API 设计只是后台的活,为什么还需要前端工程师. 作为一个程序员,我讨厌那些没有文档的库.我们就好像在操纵一个黑盒一样,预期不了它的正常行为是什么 ...

  5. 前后端分离后API交互如何保证数据安全性?

    一.前言 前后端分离的开发方式,我们以接口为标准来进行推动,定义好接口,各自开发自己的功能,最后进行联调整合.无论是开发原生的APP还是webapp还是PC端的软件,只要是前后端分离的模式,就避免不了 ...

  6. 前后端分离之【接口文档管理及数据模拟工具docdoc与dochelper】

    前后端分离的常见开发方式是: 后端:接收http请求->根据请求url及params处理对应业务逻辑->将处理结果序列化为json返回 前端:发起http请求并传递相关参数->获取返 ...

  7. SpringBoot实现JWT保护前后端分离RESTful API

    通常情况下, 将api直接暴露出来是非常危险的. 每一个api呼叫, 用户都应该附上额外的信息, 以供我们认证和授权. 而JWT是一种既能满足这样需求, 而又简单安全便捷的方法. 前端login获取J ...

  8. 前后端分离,接口API,契约

    前后端分离了,然后呢? http://icodeit.org/2015/06/whats-next-after-separate-frontend-and-backend/ Swagger - 前后端 ...

  9. [转] 前后端分离开发模式的 mock 平台预研

    引入 mock(模拟): 是在项目测试中,对项目外部或不容易获取的对象/接口,用一个虚拟的对象/接口来模拟,以便测试. 背景 前后端分离 前后端仅仅通过异步接口(AJAX/JSONP)来编程 前后端都 ...

随机推荐

  1. 【asp.net core 系列】12 数据加密算法

    0. 前言 这一篇我们将介绍一下.net core 的加密和解密.在Web应用程序中,用户的密码会使用MD5值作为密码数据存储起来.而在其他的情况下,也会使用加密和解密的功能. 常见的加密算法分为对称 ...

  2. Python学习之准备工作

    Python学习之准备工作 编程语言历史 在计算机硬件基础中我们大概介绍了一下计算机的发展历史.了解到在曾经有一段时期里计算机是不存在操作系统这一概念的,所有需要计算机完成的操作都需要当时的程序员来与 ...

  3. Python 简明教程 --- 7,Python 字符串

    微信公众号:码农充电站pro 个人主页:https://codeshellme.github.io 过早的优化代码是罪恶之源. -- Donald Knuth 目录 无论哪种编程语言,字符串处理都是最 ...

  4. Redis五种数据类型应用场景

    目录 1.1 回顾 2.1 应用场景 2.1.1 String 2.1.2 Hash 2.1.3 List 2.1.4 Zet 2.1.5 zset 3.1 小结 1.1 回顾 Redis的五种数据类 ...

  5. dart快速入门教程 (5)

    5.函数 5.1.函数定义 语法: 返回值类型 函数名(参数类型 参数1, 参数类型 参数2,...) { // 函数体 return '返回值' } 举例: void main() { print( ...

  6. dart快速入门教程 (1)

    1.环境搭建 1.1.dart简介 Dart 是一种 易于学习. 易于扩展.并且可以部署到 任何地方 的 应用 编程 语言.Google 使用 Dart 来开发 大型应用.flutter使用dart语 ...

  7. Dll的多字节和Unicode

    Dll的多字节和Unicode 分类: MFC2013-10-17 13:00 28人阅读 评论(0) 收藏 举报 dll字符集字符集多字节Unicode 我们定义dll的时候会区分: 字符集:使用多 ...

  8. 理解与使用Javascript中的回调函数 -2

    在javascript中回调函数非常重要,它们几乎无处不在.像其他更加传统的编程语言都有回调函数概念,但是非常奇怪的是,完完整整谈论回调函数的在线教程比较少,倒是有一堆关于call()和apply() ...

  9. Kubernetes 两步验证 - 使用 Serverless 实现动态准入控制

    作者:CODING - 王炜 1. 背景 如果对 Kubernetes 集群安全特别关注,那么我们可能想要实现这些需求: 如何实现 Kubernetes 集群的两步验证,除了集群凭据,还需要提供一次性 ...

  10. 【FastDFS】FastDFS 分布式文件系统的安装与使用,看这一篇就够了!!

    写在前面 有不少小伙伴在实际工作中,对于如何存储文件(图片.视频.音频等)没有一个很好的解决思路.都明白不能将文件存储在单台服务器的磁盘上,也知道需要将文件进行副本备份.如果自己手动写文件的副本机制, ...