你还不会写API文档吗

码农老张 2022 2022-10-27

一：API没人不了解吧

1.API浅谈

什么是API不会有人不知道吧？在步入软件研发之路之后，无论你是前端还是后端，还是测试，不会有人不知道什么是API吧！三次握手四次挥手，这是什么？这就是API的本质。当然，我们的日常开发途中，不会有人问你这个问题的，我们一般会说，我需要一个接口，这个接口想要实现什么功能。是的，这个接口就是API。

2.API普通规范

在协同开发中，我们需要有一套规范，才能够让前后端愉快的共同开发。因此，我们需要有一套接口规范，无论是内部严格的使用restful接口规范，还是对接外部某些三方会统一输出POST接口，这些都是团队对内部/外部约定俗成的规范。此处，我不对以上两种接口输出规范做评价，各有各的规矩，各有各的好处，仁者见仁，智者见智。

3.开发遇到的api文档

基于最近有需求，需要对一个功能模块进行大改版，这个模块之前不是本人负责的，当需求确定之后，我对这个模块的接口进行了梳理（虽然有api管理工具），以便于确定需要对哪些接口进行改造或者新增某些接口。然而，在梳理过程中，我看到了这些问题。。。

二：这些问题怎么还会存在？

对了，先提一句，我们用的是apipost软件进行接口管理。

1.接口入参没有进行注释说明

这里有四五个入参没有进行说明？谁知道是什么参数呢？要不要传？你还不会写API文档吗

2.重复属性的入参字段没有说明作用

比如下列两个字段goods_class 和good_class_group,两个字端明显一致，但是一个是字符串，一个是数组，可能想实现一个商品可以在多个分类下的需求，但是，如果这个字段是优化过的需求，那么，两个字段中必定是有一个是即将废弃的字段，此处，是需要注明TODO的。而且，在后端的代码逻辑中，也没有找到这两个字段的TODO注释,这就对其他协同开发者形成了威慑，不知道是为什么，但是不敢动。

你还不会写API文档吗

3.后端没有处理的入参

这个现象和第一个现象结合，简直是一个大💣，如下字段inventory,自我理解，这个字段指的是库存，在查询数据库文档之后，没错，就是这个意思，但是，后端并没有处理这个参数。

你以为问题就结束了？

不，问题还有...

这个神奇的字段，在数据库文档中存在，但是在代码model (用的是mongo数据库) 中不存在...

经过查询代码提交记录，找到相关人员，询问为什么？原来是，库存需求被其他方案替换了，不再数据库中存储了，只是，稍稍忘记了修改文档。。。

你还不会写API文档吗

4.后端无效的查询字段

熟悉webstorm的伙伴大家都知道这个灰色字体是什么意思吧，上下文中未引用的声明。那么，这个api中的查询条件order_id就是无效的，很明显，如果前端传入了order_id，则，返回的数据一定是错的，因为，没有进行数据匹配。

你还不会写API文档吗

5.接口时间参数处理

在我们日常的开发途中，经常会有这么一种情况，需要查询某个时间段的数据，那么如下所示，有一个问题23:59:59 < time < 00:00:00，time这一秒，数据没有被查询到。这是一个很小的问题，但是也很容易被忽视。其实只需要一个小小的修改，就可以避免这个问题，将lte改为lte改为lte改为lt，然后将$lt的时间修改为第二天的00:00:00即可。

原代码：

        Object.assign(whereStr, {
          createdAt: {
            $gte: new Date(moment(payment_time).format('YYYY-MM-DD 00:00:00')),
            $lte: new Date(moment(payment_time).format('YYYY-MM-DD 23:59:59'))
          }
        })
复制代码

修改后的代码：

        Object.assign(whereStr, {
          createdAt: {
            $gte: new Date(moment(payment_time).format('YYYY-MM-DD 00:00:00')),
            $lt: new Date(moment(new Date(payment_time).getTime() + 24 * 60 * 60 * 1000).format('YYYY-MM-DD 00:00:00'))
          }
        })
复制代码