你还不会写API文档吗

一：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…