题外话
在新的项目中,推行了swagger用于对API的设计。以期待解决我们上篇博客中说到了一些现象,提升工作效率。那么,结合到当时和全项目组成员做培训,以及后续的给主要应用者做培训,以及当初自己接触到swagger的时候,我简单总结一下如何设计一个说“人”话的API(主要指rest API)。
备注:哈哈,又托大了哈。就在我决定写这篇文章的时候,我特意到百度搜了一下“如何设计API”,额,还是决定凑凑热闹!
如何设计API呢,原则就是:KISS。 让你的API学会KISS
作为开发者来说,在开发API的时候,必须得明确:这个API提供什么服务??? 用户如何能够理解我这个API的用途......
而作为用户呢,额,想一下自己在使用API(内部的,外部的,谁管它)的时候,我就会想我如何使用已提供的API进行编码,有没有一种更好更容易的使用方案......
那么作为整个API维护的负责人来说,他可能还得考虑,API如何兼容,维护扩展
设计API,由于我们项目组采用的是swagger,所以,把文档、版本、语义上的内容,也就是可用性和可读性暂时忽略掉了。 当然,对于如何快速上手swagger设计API,等会儿还得提几个点(感觉寒寒和晶晶怎么那么聪明可爱啊,上手贼快了)
一、KISS原则
KISS原则,其实很简单,就是 keep it simple,stupid。
我相信很多人,包括我自己,有时候在写API的时候,总会纠结一些问题,比如说:目前他只需要两个参数的接口,但我感觉他可能会需要第三个参数,然后就在扩展接口的参数,然后再想了一圈,开始实施。 但这样子,又经常出现的是什么情况呢???
由于使用者只需要两个参数,但你给出了第三个(不管是否使用了重载,这是在讲rest API, 不是像接口一样根据传入的参数自动调取对应实现),那么使用者就会开始迷惑,我到底用哪一个? ???像我这种有强迫症的,我还会想,那第三个参数到底是什么???是不是我当前的设计有问题,其实是需要第三个参数的????
所以,再次强调:API需要KISS,多多KISS,你在犹豫要不要往上新添东西的时候,那答案是:不要!
二、关注关键语义
在反复强调了KISS原则之后(再次强调,因为swagger的API语义很清晰,包括协议,路径,权限,方法参数等等,一旦你不按规则做,API编辑器会报错。所以,不多说这个!)就不得不说到新手操作swagger了。在实践的过程中,发现一个现象就是,可能是由于对新事物的陌生,也或许是别的原因,无论什么。会出现不会用swagger设计API的现象,就是参数和返回值不知道写什么,怎样写多个GET方法等等。
但是,改善这个现象,只需要考虑一点:把自己当成用户,你最希望这个API提供哪些说明,那基本上,这个API就要提供这些说明!其实,这跟以往写API是一样的,当我们写一个方法时,在之前,我们通常要求说:返回类型,参数个数,参数类型,方法名(在rest API中,就是请求路径),方法注释等等。
所以,在用swagger的时候,也就照着我们以往的形式来就行了。其实,我们用swagger就是用来设计API,跟咱们以前的接口文档很类似,不同的就是,语义更加明确清晰,可视化mock测试。
像有一些别的,比如说:tags、summary、operationId一类,在最开始接触的时候,可以适当忽略。跟参加聚会似的,咱先去找到咱们熟悉的人物,然后让自己在一个环境中轻松的待下来,这时候那些咱们熟悉的人物或者我们自己,就能去发掘那些有意思,但我们目前可能还不很熟悉的内容。
说到这儿,好像跑偏了,但结合到自己半个小时从决定用swagger而没有用blueprint,到发布我第一版高可用API,和后来对于同组成员的差不多就1个小时的培训,然后她们就能无障碍使用swagger,得出的结论真的就是:从自己熟悉的入手,把新东西学旧。这就是最快的接收方式!
三、总结
像swagger,它本身就是一个全球最受欢迎的API辅助工具。那么,要做到被更多人,被很多人接受,它肯定就不会很复杂。要知道,这个世界,真的还是大众居多的。所以,心里上不要有压力,简单大方上手,so easy。 然后,它经历了几个版本,被很多很多的人应用接受,那它对于API设计这个部分,不管是规范还是别的什么,都是可见一斑的。事实上,它对于每一个API有一个框架,就跟填表格一样,直接填写就行了。还有可视化的界面用于检测,这个API是不是你想要的。
话说多了都要进去肺里,实践了就知道!