共计 1825 个字符，预计需要花费 5 分钟才能阅读完成。
一：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…