聊一聊:你碰到过哪些操蛋的文档?
公众号程序猿DD
共 537字,需浏览 2分钟
·
2021-01-29 11:24
我们一直强调,要写注释,要写文档!
写出一份好文档是一个开发者应该具备的一项重要能力!
今天在群里(点击加入),看到一个经典的来自某国企的接口文档,引发了一段时间的讨论。
在这个文档中,HTTP接口的内容格式大致是这样的:
请求路径:/api/user
请求参数:
参数 | 必填 | 默认值 | 含义 | 示例 |
name | 是 | 无 | 名称 | didi |
address | 是 | 无 | 地址 | 上海xxx |
age | 是 | 无 | 年龄 | |
gender | 是 | 无 | 性别 | |
birth | 是 | 无 | 生日 | 19900101 |
graduate | 是 | 无 | 毕业院校 | |
phone | 是 | 无 | 电话 | |
native | 是 | 无 | 籍贯 |
聪明的你,有发现什么不妥么?
这样的文档群友们打了0分,你觉得可以得几分呢?
留言说说你觉得这样的接口文档问题在哪里呢?
你还碰到过哪些让你想口吐芬芳的文档呢?
往期推荐
评论