对于接口文档的编写， 我觉得用任何工具都会有效率耗损。包括 yapi ，postman ，还有注释类的 swagger 。
接口文档特别是内部用的并且是前端用的，95%的情况就是一个简单的输出与输入，主要工作是描述清楚字段结构，主要目的是与前端达成沟通以及存档的作用，并不需要多么标准化。
而各种工具，无论是界面类的还是注释自动转换类的， 都需要遵照特定规范，按要求去填写。
点击一个输入框或是写上特定注释标记都需要额外的时间与心智消耗，这些精准规范其实没必要, 并且他们(特别是国产工具)都经不起时间的变化, 另外维护更新工作也是一个反人性大家都不想做的事情。
所以我在想在写文档的效率方面， 直接用最简单的文本是最方便的，直接在代码编辑器写注释文本，不需要遵照特定注释规范, 特别是输出参数比较多, 层级也多, 直接用所见即所得的 json 文本本身做为描述是最简单的。无需担心格式出错, 维护更新也在相同的地方, 没有割裂感. 并且他们的经得起时间的沉淀 (越简单的东西, 他们的存在度和稳定性就越高, 日后你想要转换成任何文档形式都可以. 这也是我对于笔记应用的一个观念转变: 从印象笔记到后来直接用 vscode 写 md, 到现在 md 只不过是一个文件后缀而实际很少用它的语法了, 而同步功能直接用谷歌云盘同步目录, git 不定期备份. 大道至简)
然后把我们写得不那么标准的简化注释用 ChatGPT 转换成勉强标准的结构化文档，它就适合做这类不精准的东西，还有纠错能力。
我试过了，它转换成的 postman 导入文件居然是对的，我还担心这种事情它一般会出错，不过凡涉及代码的东西最好不用，有时出错给它排错的时间不值。
[Imgur](
)