后端不写 api 文档怎么办， V 友们究竟是怎么解决的

其实我一般喜欢手写 API 文档。好处是提前思考接口逻辑

@version 太典了 一堆 Java crud 仔都是个这 入参写不清楚 什么是必传的 参数类型到底是 int 还是 string 啥都是要你模拟数据发起请求才能看到问题 清不清楚的还能说道说道 参数全整对了 最后请求报错是最崩溃的 到底写完自测不自测的啊....

@alleluya 自测这东西也不怪开发员..分情况. 一般接触 java 的项目大多都是维护..第一版的开发者老早就跑路了..因为业务需求变动改不动代码架构-java 特性..重构推不动.成本太高..这些项目会不停的叠加版本..参数未知..错误情况未知..就是一坨屎山...没人敢动..每年都会换一批 crud 人员....我应该是从 2014 年开始到目前..了解 java 接触过得基本这样..
所以我 2015 年就抛弃了 java.

@version 出新接口和旧业务基本没关系也能说不敢动吗... 我明白你说的意思 但我碰到的 crud 仔有的真的是没法说 且先不说能力高低 习惯差的厉害...

@jorneyr 成功情况 1 、成功情况 2 这种区分很少见吧，至少我没有遇到过。你可以举个例子吗？

不过 OpenAPI 3 提供了你说的解决方案，有多态 Schema.

@yetrun 不过 OpenAPI 3 提供了你说的解决方案，有多态 Schema.

例如请求一个任务的详情:
1. 如果任务是 JDBC 类型的，返回的是查询的结果集
2. 如果是 API 类型任务，会请求其他服务的数据

虽然是同一个接口，但是任务类型不同，响应的结构也不同，当然也可以把不同任务详情的接口分开，但是你能否定合在一起的情况。

@jorneyr 这就是 OpenAPI 3 中提到的多态 ref 的情况，它已经为你想到了

在以前, 我的推荐做法是后端在 postman 里写好, 再用 postman 在线文档的功能.

对于接口文档的编写， 我觉得用任何工具都会有效率耗损。包括 yapi ，postman ，还有注释类的 swagger 。
接口文档特别是内部用的并且是前端用的，95%的情况就是一个简单的输出与输入，主要工作是描述清楚字段结构，主要目的是与前端达成沟通以及存档的作用，并不需要多么标准化。
而各种工具，无论是界面类的还是注释自动转换类的， 都需要遵照特定规范，按要求去填写。
点击一个输入框或是写上特定注释标记都需要额外的时间与心智消耗，这些精准规范其实没必要, 并且他们(特别是国产工具)都经不起时间的变化, 另外维护更新工作也是一个反人性大家都不想做的事情。

所以我在认为写文档的效率方面， 直接用最简单的文本是最方便的，直接在代码编辑器写注释文本，不需要遵照特定注释规范, 特别是输出参数比较多, 层级也多, 直接用所见即所得的 json 文本本身做为描述是最简单的。无需担心格式出错, 维护更新也在相同的地方, 没有割裂感. 并且他们经得起时间的洗刷 (越简单的东西, 他们的存在度和稳定性就越高, 日后你想要转换成任何文档形式都可以. 这也是我对于笔记应用的一个观念转变: 从印象笔记到后来直接用 vscode 写 md, 到现在 md 只不过是一个文件后缀而已实际已很少用它的语法了, 而同步功能直接用谷歌云盘同步目录, git 不定期备份. 大道至简)

然后把我们写得不那么标准的注释用 ChatGPT 转换成勉强标准的结构化文档，它就适合做这类不精准的东西，还有纠错能力。
我试过了，它转换成的 postman 导入文件居然是对的，我还担心这种事情它一般会出错，不过凡涉及代码的东西最好不用，有时出错给它排错的时间不值。
[Imgur]( )