又是看 API 文档崩溃的一天

[richChou]

从业多年几乎没看到过一份合格的 API 文档。

回想了一下，接触比较多的什么京东开普勒、微信开放平台、支付宝，以及各种提供开发平台服务的小公司，就没有几个省心的文档。

包括不限于 无业务整体流程、文档结构不清晰、参数命名规则混乱、参数说明含糊不清、示例与说明不一致、出现未说明错误码 等问题。

拜托各位业务负责人、各个 Leader 、还有写文档的铁子们，写文档的时候稍微多花点心思，节约大家的沟通成本。皆大欢喜不好吗？

[memedahui]

支付宝我觉得是最好的,没有之一

[AoEiuV020]

程序员最讨厌的四件事：写注释，写文档，别人不写注释，别人不写文档

[huifer]

你可以写一个优质的文档让我们看看吗

[Tianao]

@huifer #3 同样是面向业务流程的，GitHub 的、Cloudflare 的就都很优质，不谢。

[freakxx]

天降正义：
所有事情都漂漂亮亮地处理好，就等着我按下关键的按钮。

[richChou]

@freakxx
@huifer
1. 文档的目的是产品服务给别人使用的时候，可以便捷地完成接入
2. 我们经常作为服务提供方、也是服务使用方，应该可以明白节省沟通成本是双赢的事情吧？
3. 一个合理且没有恶意的吐槽，如果你有不同的看法可以聊聊，这样冷嘲热讽挺没意思的

[qwertyzzz]

你可以写一个优质的文档让我们看看吗

[sprite82]

看楼上冷嘲热讽的，类似冰箱有问题我还得会制冷

[balabalaguguji]

请看优质的文档： https://easydoc.net/doc/30486560/ae8DEKDo/0wgri5M2

用易文档写接口文档很方便

[cmdOptionKana]

这个程序员的责任是次要，公司管理层负主要责任，要么对程序员写文档给予某种形式的奖励或鼓励，要么另外请专人写文档。不然写文档吃力不讨好，当然不爱写。

[zhengsidao]

有一说一，写接口文档国内真的是不太行
REST 参数名称 过去式 单复数都没有很好的遵守，可以看看谷歌的一些 API 接口信息，老外的 SaaS 服务为了保证对接一般都写的还可以....

[AoEiuV020]

@sprite82 别类似，你也是个冰箱，确实要会制冷，

[freakxx]

@richChou #6

> 3. 一个合理且没有恶意的吐槽，如果你有不同的看法可以聊聊，这样冷嘲热讽挺没意思的

还是挺有意思的。

比如我也可以说类似的话，
我们经常作为服务提供方、也是服务使用方，应该可以明白帮助别人改进也是双赢的事情吧？



这个事情，我只是觉得，你说这几家的文档烂嘛，已经做得挺不错的，说难用嘛，很多时候，历史遗留的问题，是留了很多坑坑挖挖；
只是很多时候，文档好不好用，在某些时候，变得不好用，这个是有部分主观的问题的；
这个事情是需要宽容一点的。

[freakxx]

@sprite82 #8

老实说，现在问题不是讨论冰箱能不能制冷的问题；
而是明知道冰箱千种万样，并且这个制冷不是每时每刻都是稳定的，也明知道保持这种稳定是很难的以至于基本不可能，还要求是这样，这样是很离谱的事；


就这个角度来说，你也是个冰箱，你能展示下 100%优质的制冷效果来看看？

[z54749412]

@memedahui 支付宝小程序不是抄的微信的？这么说就是微信比较牛批了么？

[z54749412]

@memedahui 少打了文档两个字，，非常抱歉

[freakxx]

@memedahui #1
@z54749412 #15

支付相关的文档，如果不限定的话，可以看下 stripe
接过几家的支付，接到 stripe，感觉是做得更舒服；

https://stripe.com/docs
https://stripe.com/docs/api

[InkAndBanner]

微信小商店的 api 也一样 文档仿佛是为了骗我而存在的

[AngryPanda]

@balabalaguguji 感觉美观上差了点意思

[raaaaaar]

我一直是很重视可读性，规范这种东西的，不过突然有一天有人跟我说注释写得太少。。