接 Slack 的机器人 API 有感

[Varobjs]

需要发送一些报警信息，用到机器人接口。
用过钉钉、企业微信的 机器人， 今天接入了下 slack 的，发现有很大的区别。
slack api 真的很详细，包含消息的格式，支持什么消息，文本最大长度，emoj 等等，还有消息工具可以调试。
钉钉、企业微信的接口不要太简单，记得之前想知道 钉钉最大能发多大消息，还要自己试， 支不支持换行什么的
也需要各种尝试。


真的是，不是网络问题，slack 彩虹屁可以吹爆。

国内的为什么会这样，不管公司大小，都是利益至上，都不用心做产品吗？

Stripe Api 交互确实不错，收藏了。

https://stripe.com/docs/api

[damngood]

国外很多公司的 API 文档都是这样的... 记得当年第一次对接 Stripe API 之前还没有觉得国内大厂 API 有多烂..

[lululau]

看阿里云的文档，觉得阿里的还行啊，腾讯的文档真是呵呵了

[taogen]

财迷心窍，上行下效。

[Varobjs]

@damngood 对比才知道，第一次接触国外 API
还有类似产品，差距不是一点点

[Varobjs]

@taogen 不过也能理解，周边同事包括自己，很多时候就是完成当前任务，优化东西，一不被任何，二很多情况 leader 也不许

[tmackan]

接触过 Trello, zappier
zappier 简直牛逼，各个 app 上可以联动

[Varobjs]

@tmackan zappier 看了下好像不错，以后可以试试

[kuroismith]

是这样的, 面向逆向编程

[ChristopherWu]

因为。。在国内你接 api 是你求他们。。。

[chendy]

可能因为国内重视这方面比较晚（或者到现在也不怎么重视吧）

[Varobjs]

@ChristopherWu 真相

[sikariba]

我也有类似经历，先写了 slack 感慨这文档写得真是好啊，后来要对接微信，文档版本太旧还给我挖了个坑，最后还是靠百度解决的

[pcbl]

微信支付之前的文档确实差一不小心就进坑，还好用的人多基本上你遇到的别人都遇到过。

这两天搞 tg 机器人感觉 api 也很好，交互处理很方便。

[jinliming2]

@lululau 阿里云的文档我记得之前看帖子说是直接照搬 AWS 的文档

[Varobjs]

@pcbl 既然那么多人都踩过坑了，百度都能收到，微信都不更新温度，只能说明，国内根本不重视 文档啊

[Varobjs]

收到 - 搜到
温度 - 文档
😭

[pcbl]

@Varobjs 确实不重视，或者说有点混乱，有时候新旧文档和 sdk 或者 demo 相互穿插，你还得自己猜测到底是文档太新了还是代码太旧了。

[agdhole]

国内应用给你开 api 都烧高香了，人人都要搞封闭，生怕别人接入做第三方去了

[realkenshinji]

@damngood stripe 的 api 文档算是典范了

[ClericPy]

国外独角兽企业的 api 好看+好用的不得了, Intercom 除外...

[ltm]

当造了一个墙以后，墙里没有竞争，就开始有恃无恐的堕落发展了
自由竞争才能创造更多福利（各个方面）

[asuka02]

最近对接小爱同学，小米的文档写的一头雾水。有问题只能提工单回复全看运气。之前申请小米开发者说是两个工作日审核，结果等了十天没反应，发邮件一个月后才回复。审核通过又不发邮件或者短信提醒⏰

[Varobjs]

@asuka02 摸摸头，最近接快手文档也是，
想确认下昨天数据什么时候不会再更新都很难，目前看到的是
凌晨三点 获取昨天数据，和中午获取昨天数据 有差异

快手给的回复说，不可能的

[Varobjs]

以上，有回复是因为利益相关，要是免费的东西，估计没人鸟你

[2oTp]

我们是社会主义初级阶段, 发展还没跟上, 要慢慢来, 等个 100 年或许就有了

[justfortest]

国内大部分公司风气就是这样，而且行业真的太浮躁了。

[azh7138m]

@lululau 阿里云的文档的文档也是有点烂的，气到昏厥，国外大厂哪个文档不必他强。apiVersion 那个设计蠢的要死，参数类型不对，mock 数据的问题也不说了，示例值和默认值不一样也坑到我了，一言难尽。

[avalon0624]

写完就完成任务了，怎么会理解看文档的人的感受

[ranwu]

没利益，不做

[Varobjs]

@justfortest 是太浮躁了，老板要的是，想法提出来，就要立刻、马上实现。产品经理是为老板服务。至于其他，“先实现，后面再优化” 听太多了， 结果，大部分情况是，后面自己都不想看自己代码。

[justfortest]

@Varobjs 项目经理和产品也都是一个样，各种细节和功能在开发过程中一改再改，本来就紧凑的时间就更少了，代码质量项目架构、需求文档、设计文档、接口文档也就无从谈起了，我是没见过有完善文档的项目。

[imycc]

听了老哥们推荐的 Stripe API 文档，过去瞄了一眼确实做得非常好看了，结构清晰，交互形式也挺新颖的，值得学习。

我之前工作包含了维护一个内部平台的 API，编写 API 文档。我的问题是：

1. 谁来负责写文档。编写 API 文档是个技术活，编写的人既要懂业务，又要有良好的表达能力。
2. 以何种形式来呈现文档。md 文档简单但是缺少交互能力，带有交互设计的文档又依赖人去设计跟开发。
3. 文档变更缺少规范。理论上接口的变动也要同期更新文档，才算是一个完整的更新流程。

但是最终一个问题，还是缺乏驱动力。如果编写优秀的 API 文档能成为一项“成果”，我相信开发者维护的动力会更强。但以我之前的经验来说，大多数时候是用爱发电。

还有，我觉得缺少了编写标准跟编辑平台。Swagger 那种看起来还行，但是丑，而且编辑有点麻烦，且不能集成对业务逻辑的描述，自由度我感觉不太行（也有可能是我了解不够深）

[Varobjs]

@imycc 相信大部分人都有这种疑问，
今天也去看下这个文档，如果哪里有分享他们是如何维护的就更好了

[a852695]

阿里云的短信接口文档和 demo 代码对不上就算了，提供的 SDK 库还是老的，害得我调试了老半天，你说 SDK 都是旧版本这让人怎么用，还好熟悉 Python，能改改 SDK，凑合能用，我都不相信是阿里云的人写的

[arrow8899]

@Varobjs The format and style is borrowed (with permission) from the CoffeeScript documentation, but the software generating the documentation was built in-house.

[ytmsdy]

现在阿里云 oss 的 python sdk 库现在还有 bug，现在能用的库都是第三方写的。

[exip]

从"无"到"有"是一个很大的成绩,大家都关注,从"有"到"好用"基本没人关注,做的再好也是这样.

[Sasasu]

google 的 api 就烂的很，给你一堆从 protobuf 上生成出来的东西，还不如直接去读那一堆 proto 文件。