1.为什么使用swagger?
1.1背景:
相信无论是前端开发工作人员还是后端开发工作人员,都或多或少地被接口文档折磨过,前端经常抱怨后端给的接口文档与实际情况不一致,后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。但是这个接口文档对于程序员来说,就跟注释一样,经常会抱怨别人写的代码没有写注释,然而自己写起代码起来,最讨厌的,也是写注释。所以仅仅只通过强制来规范大家是不够的,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。为了前后端的信息能够最大范围的统一规划,swagger出现了。
背景来源于
1.2 Swagger是什么?它能干什么?
Swagger 工具的强大功能始于 OpenAPI 规范——RESTful API 设计的行业标准
Swagger的强大之处:
swagger的出现增加了软件开发的开发效率,降低了前后端因为数据交互而产出的不必要麻烦
2.怎么使用Swagger?
2.1在springboot项目中添加依赖:
<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-ui</artifactId> <version>1.5.2</version> </dependency>
2.2编辑配置文件application.yml文件:
springdoc: api-docs: enabled: true path: /api-docs swagger-ui: #自定义swagger前端请求路径,输入http:127.0.0.1:8092/jt会自动重定向到swagger页面 path: /jt #jt可随意定义,最好与自己的项目名一致,方便记忆
2.3创建LoginFrom表单类,实现用户登录界面的配置
2.4创建UserController类接收前端发送的数据
2.5创建UserService接口:
2.6创建UserServiceImpl类,实现UserService接口 :
2.7创建UserMapper接口,实现ORM映射:
2.8创建UserMapper.xml文件 ,编写查询数据库的sql语言
3测试Swagger:
3.1启动后端服务器
3.2访问localhost:8093/jt
注:此处端口号一定要匹配
3.3尝试登录,看返回值是否符合要求:
3.4查看返回值是否符合要求:
3.5接口文档进行分析:
接口文档:
url请求:http://localhost:8093/user/login
curl -X POST "http://localhost:8093/user/login" -H "accept: */*" -H "Content-Type: application/json" -d "{\"username\":\"admin\",\"password\":\"admin123456\"}"
请求类型:POST请求
返回值类型:
{
"status": 200,
"msg": "服务器调用成功!",
"data": "1f9b2feb58b34f7aa01f0bc6cdc20f88"
}
好了上面都是一些入门测试的demo,下面上难度了:
这是我自己找的项目OA系统:直接看swagger页面:
4.1OA系统登陆测试:
接口文档分析:
接口文档分析:
url请求:http://localhost:8090/emos-api/user/login
请求方式:POST方式
返回值:响应结果-状态码-权限列表-token值
4.2查询所有用户:
接口文档分析:
url请求:http://localhost:8090/emos-api/user/searchAllUser
请求方式:GET方式
返回值:响应结果-状态码-data(数据源)
有兴趣的可以查看 Git源码