北京
分享至
你打开一个陌生接口文档时，最想先看到什么？一堆参数的类型、必选可选、响应码对照表，还是直接抄走一段代码，改两行就能跑通？多数开发者嘴上说着“完整”，手却很诚实——直奔示例。
最近有个观点很戳人：把文档写得滴水不漏和把文档写得顺手好用，完全是两回事。该有的端点、参数、返回码当然要有，但那不决定好坏。决定好坏的是，文档能不能第一时间回答“我怎么发起一次成功的请求”。
没人打开接口文档是为了查阅手册，大家想的都是“把这个功能调通”。你给一段复制过去就能跑的例子，信任感立马就有了。这时候开发者才愿意翻看错误码、边界行为的细枝末节。
所以，一个端点的文档结构只要三层就够了：先用一句大白话说清楚这接口是干什么的，比如“获取某个订单的详情”，而不说“返回指定资源”；再扔出一个能工作的完整请求示例，这里自动生成的代码块往往最亮眼；最后才是参考细节，参数列表、边界情况、错误码，密密麻麻也没关系。
可现实里绝大多数文档刚好搞反了：没等读者看见一行有效调用，先砸过来一堵参数墙。把这个顺序倒过来写，文档的好用程度会立刻不一样。
特别声明：以上内容(如有图片或视频亦包括在内)为自媒体平台“网易号”用户上传并发布，本平台仅提供信息存储服务。
Notice: The content above (including the pictures and videos if any) is uploaded and posted by a user of NetEase Hao, which is a social media platform and only provides information storage services.
