如何写出人见人爱的API文档?

这其实是做不到的。因为众口难调。

但要写初、中、高级开发都能用的文档的小目标，还是可以尝试一下。

如何写出初、中、高级开发都喜欢的API文档呢？要点在哪呢？

Don't make me think!

在讲怎么写之前，想想下怎么用？

使用官方的SDK，无非是觉得官方对服务的情况知根知底，写得靠谱；无法是想低成本地接入这个服务/中间件，最好是copy+paste，然后一次调通，然后上线。

做为一个接过N多个服务的老程序员，再具像化下用户的要求：

1、能找到，最短路径找到。最好是在SDK中放个文档连接，或者SDK源码中已经包含了使用说明。

java.nio.file.Paths#get(java.lang.String, java.lang.String...)

2、能看懂。Don't make me think!

所见即所得，目之所及，该有的都有了。既全面，又内聚。

要由浅入深、循序渐进。譬如并不是所有的开发都能拿捏多线程，并不是所有的开发都知道重试，并不是所有的开发都会有安全的Sense。

想调用远程大模型，肯定得先有一个发起请求的客户端吧。 怎么初始化一个客户端？ 先给一个最基本的示例。要使用，至少得填个apiKey吧。 还想再使用得再高级一点？ 请求报错了怎么办？是不是参数不合理？设置连接超时时间和接收数据超时时间。 除了超时，就没有其它报错的可能了？有，那得给个兜底的吧。进行重试。 唐成，公众号：的数字化之路看了字节的开发文档，我知道阿里的差在哪了

如果有不方便写在本页文档中的，要写上说明，加上链接。打开链接时要跳转浏览器新窗口，不能把当前正在看的页面覆盖掉了。

简单来说：手把手、有进阶、一站式。

手把手，不多说，都懂。

有进阶：也就是小白玩得很开心，资深的玩的也很开心。有的是玩具项目，用默认的就行；有的是对时延敏感的项目，想快一点；有的是大数据量的项目，需要快一点，就是多线程。多线程就关心是否线程安全，最好很直白的写出来，最好封装好。

当您的业务有较高的请求量，您可以通过单例模式结合线程池和连接池来调整并发调用，以应对不同的并发需求。 建议： 每个进程仅初始化ArkService一次，作为单例使用。多次初始化会构建多个线程池以及连接池。 进程退出前需要使用 service.shutdownExecutor() 关闭线程池。 唐成，公众号：的数字化之路看了字节的开发文档，我知道阿里的差在哪了

3、够安全。

这个算基本的，也是高阶的。

每次安全扫描都扫出OSS的问题。有的是SDK使用不当，有的是as,sk的权限范围没有卡好，一个ak拥有所有bucket的权限，有的是因为把ak,sk写到前端了，而不是使用STS的方式。

还有线程安全，如上。

4、要正确。

像上面这种安全。

注：这是2020-05月份的事了，后来阿里云上的文档已fix。不过事故我们团队也背了。就是上传的商品图片过几天就丢失了，直接影响生产了。

总结：

用户怎么省劲怎么来。不要让我思考上哪找，应该就是手头边；不要让我思考怎么用，直接Step by step copy+paste就可以了；不要让我担心有安全隐患，为什么安全写在边上，让我放心；不要让我再二次封装，来解决重试、多线程、池化、处理异常等NFR特性；

省找的时间；

省理解的时间；

省fix安全漏洞的时间，越是重要的服务，这方面越好的支持；

省自己二次封装的时间，大数据量要支持并发、低延时要有这个入口、失败时要重试的能力要有通知的抓手。。。