一：API没人不理解吧
1.API浅谈
什么是API不会有人不晓得吧？在步入软件研发之路之后，无论你是前端还是后端，还是测试，不会有人不晓得什么是API吧！
三次握手四次挥手，这是什么？这就是API的实质。
当然，咱们的日常开发途中，不会有人问你这个问题的，咱们个别会说，我须要一个接口，这个接口想要实现什么性能。是的，这个接口就是API。
2.API一般标准
在协同开发中，咱们须要有一套标准，才可能让前后端欢快的共同开发。因而，咱们须要有一套接口标准，无论是外部严格的应用restful接口标准，还是对接内部某些三方会对立输入POST接口，这些都是团队对外部/内部约定俗成的标准。
此处，我不对以上两种接口输入标准做评估，各有各的规矩，各有各的益处，仁者见仁，智者见智。
3.开发遇到的api文档
基于最近有需要，须要对一个功能模块进行大改版，这个模块之前不是自己负责的，当需要确定之后，我对这个模块的接口进行了梳理（尽管有api管理工具），以便于确定须要对哪些接口进行革新或者新增某些接口。然而，在梳理过程中，我看到了这些问题。。。
二：这些问题怎么还会存在？
对了，先提一句，咱们用的是apipost软件进行接口治理。
1.接口入参没有进行正文阐明
这里有四五个入参没有进行阐明？谁晓得是什么参数呢？要不要传？
2.反复属性的入参字段没有阐明作用
比方下列两个字段goods_class 和good_class_group,两个字端显著统一，然而一个是字符串，一个是数组，可能想实现一个商品能够在多个分类下的需要，然而，如果这个字段是优化过的需要，那么，两个字段中必然是有一个是行将废除的字段，此处，是须要注明TODO的。
而且，在后端的代码逻辑中，也没有找到这两个字段的TODO正文,这就对其余协同开发者造成了威慑，不晓得是为什么，然而不敢动。
3.后端没有解决的入参
这个景象和第一个景象联合，几乎是一个大，如下字段inventory,自我了解，这个字段指的是库存，在查询数据库文档之后，没错，就是这个意思，然而，后端并没有解决这个参数。
你认为问题就完结了？
不，问题还有...
这个神奇的字段，在数据库文档中存在，然而在代码model (用的是mongo数据库) 中不存在...
通过查问代码提交记录，找到相干人员，询问为什么？原来是，库存需要被其余计划替换了，不再数据库中存储了，只是，稍稍遗记了批改文档。。。
4.后端有效的查问字段
相熟webstorm的搭档大家都晓得这个灰色字体是什么意思吧，上下文中未援用的申明。
那么，这个api中的查问条件order_id就是有效的，很显著，如果前端传入了order_id，则，返回的数据肯定是错的，因为，没有进行数据匹配。
5.接口工夫参数解决
在咱们日常的开发途中，常常会有这么一种状况，须要查问某个时间段的数据，那么如下所示，有一个问题
23:59:59 < time < 00:00:00，time这一秒，数据没有被查问到。
这是一个很小的问题，然而也很容易被忽视。
其实只须要一个小小的批改，就能够防止这个问题，将lte改为lte改为lte改为lt，而后将$lt的工夫批改为第二天的00:00:00即可。
三：怎么写好api文档
其实在不同的公司，api文档的输入形式是不同的，因为自己所在公司应用的是apipost软件进行api治理。那么这篇文章中就先来谈谈如何应用apipost进行api文档治理。
动静路由
应用规范的动静路由的写法，利于其余协作者共同开发，以及展现你参数的取值起源。善用门路变量，事倍功半。
学会"锁定"API
apipost有一个锁定api的性能，在锁定之后，其余合作着能批改其中的参数，然而只能在本人本地批改，无奈保留，这样就防止其余协作者误操作，将api批改的惨不忍睹。
api左侧还有一个api状态的选项，能够在api开发结束之后批改为"已实现"，约定为前端可调用。
提取字段和形容
这个性能其实就是记录入/出参形容，然而这个形容，会主动获取“参数形容库”中的第一个形容，如果一个字段在不同的接口中代表不同的含意，就须要在提取时，进行查看。
四：API文档延长
不同的公司，应用的是不同的API管理工具，每个工具都有其实用的点，长于发现，长于应用。
当然，有更多的和其余公司单干的机会时，一个api接口的word文档，就很有必要了。那么，一个合格的接口word文档是怎么样的？能够查看以下文章！
juejin.cn/post/713723…