接口文档没人看，差在例子是假的

文档很完整，字段是编的

文章列表的说明写了地址、方法、参数，看起来齐全。例子是这样的：code 为 0，data 是一个空对象。模型很会写出这种例子。它整齐、通用，也和真实响应无关。

真实返回里，列表在 list，总条数在 count，文章编号是 id，分类是 article_cate_id。没有一个叫 data 的对象。对接的人按文档写了下午，页面一直空着。他没有读错字，他读的例子是假的。

一份能用的文档只要三块

一块成功的真实响应。从正在跑的环境里复制，改掉隐私，留下字段名。就这个列表而言，至少要让人看见 list、count、id、title。空对象说明不了结构。

一块失败的真实响应。未登录、分类不存在、参数缺了，各是什么样。如果失败也是 code 不为 0 再加一句 msg，就把这句真的 msg 贴出来，不要写成「返回错误信息」。

一个能直接发出去的请求。方法、路径、一个真实存在的分类编号。对方复制就能看到和文档相同的字段。复制之后对不上，文档就还没写完。

参数表格可以有。它应该排在真实例子后面。人是对着例子写代码的，表格是用来查某个字段能不能空。

让模型写文档时，把例子钉死

先自己请求一次，把响应正文交给它，并写明：例子里的字段名必须来自这段响应，不许改成 data、result、items 这一类它更熟悉的名字。它可以补句子，不能换字段。

写完之后做一次对照：文档例子里的每个键，响应里都有；响应里对接必须用的键，例子里都有。对不上的那一个，就是下一个人要浪费的一下午。

文档没人看，常常不是因为写得短。是因为读者按例子做了，做出来的和线上不一样。他把文档合上是对的。