我们一直强调,要写注释,要写文档!
写出一份好文档是一个开发者应该具备的一项重要能力!
今天在群里(点击加入),看到一个经典的来自某国企的接口文档,引发了一段时间的讨论。
在这个文档中,HTTP接口的内容格式大致是这样的:
请求路径:/api/user
请求参数:
参数 |
必填 | 默认值 |
含义 |
示例 |
name |
是 |
无 | 名称 |
didi |
address |
是 | 无 |
地址 |
上海xxx |
age |
是 | 无 |
年龄 |
|
gender |
是 |
无 |
性别 |
|
birth | 是 | 无 | 生日 |
19900101 |
graduate | 是 |
无 | 毕业院校 | |
phone |
是 |
无 | 电话 |
|
native |
是 | 无 |
籍贯 |
聪明的你,有发现什么不妥么?
这样的文档群友们打了0分,你觉得可以得几分呢?
留言说说你觉得这样的接口文档问题在哪里呢?
你还碰到过哪些让你想口吐芬芳的文档呢?
往期推荐
本文分享自微信公众号 - 程序猿DD(didispace)。
如有侵权,请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”,欢迎正在阅读的你也加入,一起分享。