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