RESTful API接口文档规范小坑

简介: 希望给你3-5分钟的碎片化学习,可能是坐地铁、等公交,积少成多,水滴石穿,谢谢关注。   前后端分离的开发模式,假如使用的是基于RESTful API的七层通讯协议,在联调的时候,如何避免配合过程中出现问题?这里分享一些不成熟的浅见。
+关注继续查看

希望给你3-5分钟的碎片化学习,可能是坐地铁、等公交,积少成多,水滴石穿,谢谢关注。

  前后端分离的开发模式,假如使用的是基于RESTful API的七层通讯协议,在联调的时候,如何避免配合过程中出现问题?这里分享一些不成熟的浅见。

Swagger描述

  我们在前后端配合的过程中,使用了大多数人使用的Swagger作为服务描述文档,这样的好处很明显,就是后台编写注释,接口调用界面自动生成字段描述。如下图:

  

  随着前后端磨合,默契程度逐步增加,基本上这种描述文档足够联调了。事物总是多变的,随着新人的加入和接口的增加,业务的复杂化,过了大半年,回头望月,接口已经开始出现坏味道。

  

  新人不知道如何维护,连老人也要梳理回忆半天,接口膨胀导致分类不清晰,很难想象如果这个时候,如果你们需要把部分前端功能进行外包会怎样?前端单看Swagger会不会一脸懵逼?

Wiki文档

        于是内部开个了专题会,参照市面上大多数的api描述文档,大家同意写到wiki,虽然这种做法除了增加后端人员的工作量,对提升效率不是那么明显,但是整个接口的描述相对就规范一些。

  

  过了一段时间,有一个前端新人进来,带来了小小的烦恼,由于后端接口变更,文档没有及时更新,前端在联调时候经常一脸懵逼,如果能及时发现还好,否则将错就错,测试没注意,发布后经常犯一些写错别字的低级错误。

  更加麻烦的是,项目工期赶,决定对前端部分模块进行外包。于是准备好了UI图和接口描述文档,觉得应该可以安心了。承包方拿到UI和文档的时候,除了简单的增删改查接口大概能猜的懂,其他的接口和UI上如何一一匹配?好吧,这该死的接口文档。

图文描述

  于是后台兄弟加班加点在UI上给每个功能一一标注对应的接口名称,如下所示,虽然缓解了前端的困惑,但是前后端分离导致的一些效率损失,始终让人耿耿于怀。也许就像DBA经常说的,任何事物都是有代价,不知道大伙有更好的解决方案赐教?

  

个人小结

1.对前端组件进行分类

比如树、表格、下拉、radio、复选框、时间……越早分类对后面的管理应该会更加有利,因为不同的新人进来,可能同样的树会重新造一种格式。

2.接口数量要控制好

 不能太多导致失控,也不能重复两份接口(不同的开发者完全有这种可能),不同的前端组件比如easyUI和elementUI对格式要求是不一样的,如果前后台用的不是同一套UI框架,接口有可能会出现重复。

3.如何规范

每个公司规范不尽相同,可以参考大厂的规范,比如高德,微信或者百度地图。对新入职的新要培训在前,开发中出现新的问题,最好要有专题会进行讨论协商一致,最后口头的东西务必要文档化,否则都不能算是真正的规范。

 

后话

随着团队人数、业务扩大,如果没有很好的规范,碰到沟通冲突的情况,规范就显得特别重要。我们团队原本两个前后端配合融洽,相安无事,后面来了两个新的前后端,由于言语冲突,一件简单的小事会因为个性不合而被无限放大。尽快统一风格,规范文档化也许可以避免很多类似的问题。

这里给哪些想要做前后端分离的人一个不错的RESTful API的规范,是阮一峰大神的博客,非常值得收藏,推荐下:RESTful API 最佳实践

 

目录
相关文章
|
2天前
|
API
【Express】—get请求参数 restful API
【Express】—get请求参数 restful API
【Express】—get请求参数 restful API
|
12天前
|
JSON 监控 测试技术
RESTful API设计与实现在员工行为监控系统中的数据交互接口(Go语言)
在现代企业环境中,对员工行为进行监控已经成为确保组织安全和合规性的重要手段。为了提高监控系统的效率和可靠性,自动化测试在系统开发过程中发挥着关键作用。本文将探讨在员工行为监控系统开发中采用JUnit进行自动化测试的实际应用,并通过代码示例演示其工作原理。
52 1
|
17天前
|
设计模式 Java API
使用Spring框架创建一个RESTful API,实现学生信息的管理,包括资源的创建、读取、更新和删除。
在当今的Web应用程序开发中,RESTful API(Representational State Transferful Application Programming Interface)变得越来越重要。Spring框架提供了强大的工具和功能,以便轻松创建、读取、更新和删除(CRUD)资源。在这篇文章中,我们将深入探讨如何使用Spring框架创建一个RESTful API,并通过一个完整的示例演示。
|
17天前
|
前端开发 Java API
什么是RESTful API,Spring MVC如何支持RESTful架构
RESTful API(Representational State Transfer)是一种基于HTTP协议的软件架构风格,用于设计网络应用程序的API。它强调使用标准的HTTP方法(GET、POST、PUT、DELETE等)来进行资源的操作,以及使用URI来标识资源。RESTful API的设计目标是简单、可扩展、易于理解和使用。
|
18天前
|
JSON API 数据格式
使用Python构建RESTful API:Flask和FastAPI的对比与实践
在现代Web开发中,构建RESTful API是一项常见任务。Python提供了多个框架来简化这个过程,其中Flask和FastAPI是两个备受欢迎的选择。本文将对比Flask和FastAPI,并通过实际示例展示它们的用法和优势。
|
2月前
|
前端开发 Java API
# Spring MVC与RESTful API:如何设计高效的Web接口
# Spring MVC与RESTful API:如何设计高效的Web接口
33 0
|
2月前
|
XML 前端开发 JavaScript
【RESTful API的组成部分】
【RESTful API的组成部分】
|
2月前
|
Oracle 关系型数据库 API
C# LIS检验系统源码,接口技术:RESTful API + Http+WCF
LIS检验系统一种专门用于医院化验室的计算机系统,它致力于提高医院化验室的工作效率和检测准确率。LIS系统由多个子系统组成,包括样本管理系统、质控系统、检验结果管理系统、报告管理系统等。体系结构:Client/Server架构 SaaS模式 客户端:WPF+Windows Forms 服务端:C# +.Net 数据库:Oracle 接口技术:RESTful API + Http+WCF
|
3月前
|
存储 JSON API
OData API 和 Restful API 这两个概念的区别和联系
OData API 和 Restful API 这两个概念的区别和联系
32 0
|
3月前
|
存储 Web App开发 Java
使用 jMeter 对需要 User Authentication 的 Restful API 进行并发负载测试
使用 jMeter 对需要 User Authentication 的 Restful API 进行并发负载测试
45 0
相关产品
云迁移中心
推荐文章
更多