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 最佳实践

 

目录
相关文章
|
14天前
|
缓存 安全 API
RESTful与GraphQL:电商API接口设计的技术细节与适用场景
本文对比了RESTful与GraphQL这两种主流电商API接口设计方案。RESTful通过资源与HTTP方法定义操作,简单直观但可能引发过度或欠获取数据问题;GraphQL允许客户端精确指定所需字段,提高灵活性和传输效率,但面临深度查询攻击等安全挑战。从性能、灵活性、安全性及适用场景多维度分析,RESTful适合资源导向场景,GraphQL则适用于复杂数据需求。实际开发中需根据业务特点选择合适方案,或结合两者优势,以优化用户体验与系统性能。
|
16天前
|
JSON 编解码 API
Go语言网络编程:使用 net/http 构建 RESTful API
本章介绍如何使用 Go 语言的 `net/http` 标准库构建 RESTful API。内容涵盖 RESTful API 的基本概念及规范,包括 GET、POST、PUT 和 DELETE 方法的实现。通过定义用户数据结构和模拟数据库,逐步实现获取用户列表、创建用户、更新用户、删除用户的 HTTP 路由处理函数。同时提供辅助函数用于路径参数解析,并展示如何设置路由器启动服务。最后通过 curl 或 Postman 测试接口功能。章节总结了路由分发、JSON 编解码、方法区分、并发安全管理和路径参数解析等关键点,为更复杂需求推荐第三方框架如 Gin、Echo 和 Chi。
|
4月前
|
前端开发 Cloud Native Java
Java||Springboot读取本地目录的文件和文件结构,读取服务器文档目录数据供前端渲染的API实现
博客不应该只有代码和解决方案,重点应该在于给出解决方案的同时分享思维模式,只有思维才能可持续地解决问题,只有思维才是真正值得学习和分享的核心要素。如果这篇博客能给您带来一点帮助,麻烦您点个赞支持一下,还可以收藏起来以备不时之需,有疑问和错误欢迎在评论区指出~
Java||Springboot读取本地目录的文件和文件结构,读取服务器文档目录数据供前端渲染的API实现
|
4月前
|
XML JSON API
Understanding RESTful API and Web Services: Key Differences and Use Cases
在现代软件开发中,RESTful API和Web服务均用于实现系统间通信,但各有特点。RESTful API遵循REST原则,主要使用HTTP/HTTPS协议,数据格式多为JSON或XML,适用于无状态通信;而Web服务包括SOAP和REST,常用于基于网络的API,采用标准化方法如WSDL或OpenAPI。理解两者区别有助于选择适合应用需求的解决方案,构建高效、可扩展的应用程序。
|
4月前
|
机器学习/深度学习 设计模式 API
Python 高级编程与实战:构建 RESTful API
本文深入探讨了使用 Python 构建 RESTful API 的方法,涵盖 Flask、Django REST Framework 和 FastAPI 三个主流框架。通过实战项目示例,详细讲解了如何处理 GET、POST 请求,并返回相应数据。学习这些技术将帮助你掌握构建高效、可靠的 Web API。
|
5月前
|
存储 机器学习/深度学习 人工智能
如何使用非结构化 API 高效处理文档
手动处理非结构化文档面临格式不一致、数据噪声多和信息检索困难等挑战,导致低效率和合规风险。Unstructured API 通过自动化文档处理,利用AI技术简化分类、归类和异常检测,节省时间和提高准确性。Supametas.AI 作为领先平台,支持多种文件类型(如文本、图片、视频),适用于各行各业,可与Salesforce、Zendesk等工具无缝集成,确保数据流动顺畅并提升工作效率。其强大的功能包括数据摄取、处理技术、检索增强生成、灵活性、可扩展性和集成能力,帮助企业和小公司高效处理大量非结构化数据,实现业务增长和优化工作流程。
233 4
|
6月前
|
开发框架 数据可视化 .NET
.NET 中管理 Web API 文档的两种方式
.NET 中管理 Web API 文档的两种方式
88 14
|
6月前
|
JSON Cloud Native API
API 规范和设计
今天主要和大家分享的是如何给予 Open API 3.0 标准来设计一套 API 规范。那么整体我们在讲的过程中,大约有以下五方面。 1. 大环境介绍 2. API与服务开放 3. API定义 4. 模型 5. 总结
563 5
|
6月前
|
API 开发者
通义灵码 API 开发文档自动生成场景DEMO
通义灵码API开发文档自动生成场景DEMO展示了通过自定义指令,大模型能快速根据类代码生成Markdown格式的API文档。文档详细描述API的入参、出参,并可生成测试代码等示例,帮助开发者快速创建美观的API文档。
290 1
|
Web App开发 测试技术 API
Spring-Boot + Swagger2 自动生成API接口文档
spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口。这些接口不但会服务于传统的web端(b/s),也会服务于移动端。
2263 0
AI助理
登录插画

登录以查看您的控制台资源

管理云资源
状态一览
快捷访问

你好,我是AI助理

可以解答问题、推荐解决方案等