Swagger的使用

此篇文章涉及到其他方面，例如：Resultful api规范，https协议

一、在开篇讲解swagger之前，首先来了解下resultful api规范

1、Resultful简介：

Resultful是一种比较流行的一种API规范，结构清晰，便于前端开发者进行区分访问接口资源

2、Resultful风格接口：

Rest是一种架构风格，表示的是Representational State Transfer表现状态转移，客户端通过访问url来获得网络上的资源表征，获得资源表征来抓变应用的状态。网络中的所有数据可分为（增删改查）四种操作，通过这四种操作获取到的则是分布在网络中的资源，将一切数据视为资源是Rest与其他架构风格最大的不同之处
Rest是一种面向资源的架构风格

3、操作分类

对于不同的操作可以分为get、put、delete、post，只用的协议是https
Get获取资源、put更新资源（put在服务器更新全部的资源，patch是在服务器上更新局部的资源）、delete删除资源、post创建资源

4、常见的状态码

200 ok服务器成功返回用户的请求数据
201 create用户创建或修改数据成功
202 accep有一个请求进入后台排队
204 No Content删除数据成功
400 用户发送的请求有错误，服务器没有进行新建或修改的操作
401 用户没有权限，用户名、密码错误
403 用户得到授权，但是访问被禁止
404 用户发出的请求是不存在的记录，服务器没有进行操作
406 用户请求的格式不对
410 用户请求的资源被永久删除，不会被获得
500 服务器错误，用户无法进行判断是否请求成功
200 系列是成功的，400系列是客户端，500系列是服务器

二、在这里解释下上面提到的https协议

https协议是身披SSL外壳的http，https是一种通过计算机网络进行安全通信的传输协议，经由Http进行通信，利用SSL/TLS建立全信道，加密数据包。Https使用的主要目的是提供对网站服务器的身份认证，同时保护交换数据的隐私和完整性
TLS是传输层加密协议，前身是SSL协议，有时候两者不区分
多说句废话：SSL及其继任者传输层安全（Transport Layer Security，TLS）是为网络通信提供安全及数据完整性的一种安全协议。TLS与SSL在传输层与应用层之间对网络连接进行加密。

三、Swagger

1、swagger简介

Swagger是一个自动生成API说明文档的工具，帮助我们更好的实现前后端分离。官方介绍说swagger是一个规范的完整的框架，主要是用于生成、描述和调用以及可视化的Restful风格的WEB服务，是简单又强大的Restful API文档在线自动生成器

2、在项目中集成swagger自动生成API文档

    1、首先，肯定是jar依赖的引入，我是gradle项目，在这里就按gradle项目演示了，maven项目的可以自己去下载jar包

    2、相关配置类，我自己的项目是把swagger给自己封装好的，不用进行配置类

如果是自己去定义一个与swagger相关的Config类，可以参考这篇文章
https://blog.csdn.net/qq_46387088/article/details/108753227
    3、方法上面添加注解，配置需要解析的接口方法
@ApiOperation 这个注解是显示的在swagger上面看到的接口注释
@PostMapping 这个注解就是请求方式跟请求名字了，相关的还有@PutMapping、@DeleteMapping、@GetMapping
    4、在网页上看我们的请求，如果你是本地启动的话可以直接访问：
http://127.0.0.1:9666/swagger-ui.html#/ 端口号根据你自己项目去填写
然后我们就可以看到我们所写的接口了

点开这个接口我们可以看到

是不是迫不及待的想要尝试了呢，点击try it out

传我们想要查询的参数之后，点击execute

需要注意的是，在后台进行传参接收的时候，需要加上@RequestParam或者@RequestBody注解，不然进行传参的时候后台有可能接收不到数据
下面我们就可以看相关的返回信息了

这里面的相关信息一看就可以懂，就不一一解释了