今天是孤尽班学习的第13天,今天学习了接口文档的编写规范
接口文档
1.接口文档的作用
接口文档是定义后端系统与前端系统交互的规则,用于在项目开发过程中,项目团队中前端人员和后端人员沟通系统交互的一个媒介,接口文档可以减少后端人员与前端人员之间的对于数据接收和返回的沟通量,在系统设计上可以减少一些参数不一致,数据内容不规范,不完整的问题,提升系统的后续的开发的效率,保障系统的高可用,低问题率;
2.接口文档编写的规范
接口文档的需要对除了包含接口定义以外,还需要对接口所实现的业务进行描述,在后续开发过程可以使开发人员对接口定义规则的理解,方面开发人员对于接口开发中的一些问题的处理能力,提高开发效率
接口文档中接口内容包含:
方法、uri、请求参数、返回参数
1)方法:GET PUT POST DELETE 等
2)uri:
以/业务名称、操作类名/操作(CRUD) 来命名
例如:
user/deleteById 用户信息按照ID来删除
user/queryId(login) 用户信息按照ID来查询
user/insert 新增用户信息
user/updateById 根据Id更新用户信息
3)请求参数和返回参数:
请求参数和返回参数都分为:字段、说明、类型、备注、是否必填。
字段:类的属性
说明:中文释义
类型:属性的类型,只有String、Number、Object、Array四大类
备注:解释说明场景语或简单的示例
4)返回参数:
只返回接口调用成功或者失败:code、reason
返回参数:字段、类型
接口的传输协议:Http等
Header头:携带的信息(token等)
3.接口文档编写实例
4.java实现接口文档的技术
swagger
官网:https://swagger.io/
使用参考:https://blog.csdn.net/weixin_37509652/article/details/80094370