你的接口很好，但在使用者眼里，它可能只是个打不开的黑盒

有过"考古式开发"的经历吗？
你接手了一个离职同事留下的老项目，或者在一个庞大的微服务群里找到了一个看似完美契合需求的内部接口。你满怀期待地点击文档链接，结果页面上只有冷冷清清的一行字：TODO: 待补充。
你只能咬着牙去翻源码。从 Controller 顺藤摸瓜到 Service，再到深埋在 DTO 里的参数定义。你试着传了 userId，报错 400 Bad Request；改传 user_id，依然报错。最后你通过断点调试才发现，这个参数需要嵌套在 header 对象里，而且必须是 Long 类型。
那一刻，哪怕在这个接口内部运用了最精妙的设计模式，优化到了极致的性能，在你眼里，它依然体验极差。
在软件工程中，代码是写给机器执行的，而文档是写给人类理解的。在微服务和前后端分离盛行的今天，API 文档本质上就是开发者的 UI。

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

东西不错很实用谢谢分享