API 驱动的程序员弑神之路（一）

什么是api，全称是Application Programming Interface，翻译过来就是应用编程接口。为啥要有这玩意，我琢磨着可能是这么回事：我们人类的智能水平比较高，可以进行复杂的语言交流，比如：“这西瓜多少钱？”“两块钱一斤”“给我来半个”。但是计算机程序就比较智障，为了避免它理解错我们的命令，就需要一个确定的格式来和程序进行交流。有了API，我们的程序就有了耳朵和嘴巴，可以听命令，可以回答了。对于程序员来说，写得一手漂亮的API，你的程序就变得耳聪目明，伶牙利齿，自然能为你的能力加分不少。

这条道路并不轻松，有很多艰难阻碍，魑魅魍魉妖魔挡在前面，需要你的恒心和勇气，虚心学习，勇敢尝试。好在，我们有一些非常棒的武器，能帮助你设计出好用的API。在基本掌握了这些武器之后，我们可以参考一些成功的商业案例，理解它们的API设计，观察它们的优缺点，最后设计并实现我们自己的API。

一，Swagger

Swagger 是一种用来描述api的规范，同时也是一个生成api文档的工具。

Swagger有两个版本，常用的是2.0，据说3.0更好用，但是postman不支持。这里我们就看一下2.0的写法：

swagger: '2.0'
复制代码

顺便说一下，这是yaml文件，常用来写一些配置信息。其实很好读懂，带有:的，左边是key，右边是value。如果把value移到下一行，就需要两个空格的缩进。带有-号的，右边是list里的一个元素。list作为value的时候不需要缩进。

tags:
- name: Accounts
- name: Orders
- name: Products
复制代码

tags 是对各个api的标签，这里我们定义了三个不同名字的标签。

虽然swagger是一个很好的编写api文档的工具，文档毕竟是给人看的，有时候直接写出来的文档会比swagger生成的要更详尽更清晰易懂。总的来说，写好swagger可以让我们对与业务需求有一个大概的了解。这是一把蝴蝶刀，用到出神入化可成绝世高手，初学者也可以用来削水果。

转载于:https://juejin.im/post/5bebe63b51882518805ab266