API生命周期第二阶段——设计：如何设计API（基于swagger进行说明）

题外话

在新的项目中，推行了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是不是你想要的。 

话说多了都要进去肺里，实践了就知道！