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