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

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

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

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

MrSheng

20 天前

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

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

原文链接：

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

Chicagoake

20 天前

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

DinnyXu

20 天前

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

gadfly3173

20 天前

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

clf

20 天前

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

还有些命名也很逆天的。

clf

19 天前

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

这是一个专为移动设备优化的页面（即为了让你能够在 Google 搜索结果里秒开这个页面），如果你希望参与 V2EX 社区的讨论，你可以继续到 V2EX 上打开本讨论主题的完整版本。

https://ex.noerr.eu.org/t/1140662

V2EX 是创意工作者们的社区，是一个分享自己正在做的有趣事物、交流想法，可以遇见新朋友甚至新机会的地方。

V2EX is a community of developers, designers and creative people.

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

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