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