聊一聊:你碰到过哪些操蛋的文档?

DD的博客全面升级,阅读体验更佳(尤其是系列教程),后续不再通过这里发布新文章,而是改到 www.didispace.com 发布啦,奔走相告!点击直达~

我们一直强调,要写注释,要写文档!写出一份好文档是一个开发者应该具备的一项重要能力!

今天在群里(点击加入),看到一个经典的来自某国企的接口文档,引发了一段时间的讨论。

在这个文档中,HTTP接口的内容格式大致是这样的:

聪明的你,有发现什么不妥么?

这样的文档群友们打了0分,你觉得可以得几分呢?

说说我的看法

  1. 作为API请求,没有给出请求类型(GET、POST…)的说明
  2. 没有给出请求格式(表单?JSON?)的说明
  3. 请求参数没有参数类型、参数格式以及合法校验的规则说明
  4. 请求响应格式的说明
  5. 请求异常响应的格式说明

就说这么说吧,换你思考了,想想看是否还有其他的问题呢?点击这里来评论区说出你的想法吧!

或者想看看其他群友的想法,点击这里直达!