你还不会写API文档吗

最新推荐文章于 2024-04-29 22:03:28 发布

原创

最新推荐文章于 2024-04-29 22:03:28 发布 · 303 阅读

标签

#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注释,这就对其他协同开发者形成了威慑，不知道是为什么，但是不敢动。