钉钉的 api 文档和调用方式 这是人能写的？还是故意写的这么乱的？

[wuyiccc]

钉钉的 api 文档和调用方式 这是人能用的？

这几天研究了一下钉钉的 api+java sdk 文档, 结果发现
1. 接口文档跟 sdk 调用方式给的字段不一样, 互相缺字段
2. 每个接口都有时间这个字段，有的是时间戳，有的是 yyyy-MM-dd HH:mm:ss, 有的是 UTC 带 Z 还带 T 的，有的是 Date ，有的是字符串，反正能有的格式全都有是吧？
3. 接口分页判断，nextToken, 接口参数 nextToken 是 Long ， 文档要传接口返回的 nextToken 的值，结果返回的 nextToken 是一个字符串？？？

钉钉你丫的是故意这么写的文档和 sdk ，逼别人买你的服务是吧？

[LieNoWell]

阮一峰《科技爱好者周刊 353 期》《胶水工作重要吗？》刚好提到了这个问题，供参考。

写文档是一份重要但不考核的工作，因此在很多大厂中都没有那么受待见。所以肯定不是故意写的，但是也没有用心就是了。

原文链接：

https://www.seangoedecke.com/glue-work-considered-harmful/

[Chicagoake]

千牛（淘宝店铺后台）的文档也是乱得要死，写贼长，语言表达上还毛病贼多，写得很难看。

[syubo2810]

钉钉接口就是一团垃圾，限制也多，文档也烂，还经常出问题

[zhroyce]

微信小程序的文档也很难理解

[DinnyXu]

相互开发的人都陆陆续续离职了，后面的人又不敢改前面的文档，哪怕是要参考也需要大量时间，所以自己加一些东西后，又没办法与前面对应，这是很正常的，至于为什么前后不能呼应，很多东西不一致，是因为没有一个技术稳定输出的总负责人，你可以理解为写标书都会有人专门写专门审核的，文档也是一样，只有写，没有审核的东西。

[superrichman]

敏捷开发：只管拉不管擦 🐶

[Bologna]

飞书也是大同小异

[gadfly3173]

long 返回字符串才是正确操作吧，万一调用方是 js 之类的环境，处理不了 long 呢？ sdk 是会处理的

[lychee930224]

“不是，你上班没写过文档吗？”哈哈哈

[clf]

阿里的所有 API 的 SDK 都没法看。找个一阿里云的 SDK 调用，能给你好多个 SDK 版本，每个版本调用方式不一样。

还有些命名也很逆天的。

[daiisdai]

@clf 简直是一坨屎，文档和 sdk 根本不一致，你都不知道哪个正确，只能一点点试

[clf]

@daiisdai 对的。目前各家用下来，反而是华为云的 SDK 用的最舒服，真的就网页上的文档和 SDK 高度一致（除了功能和 API 更新不会告知用户外）