这是一个创建于 1166 天前的主题，其中的信息可能已经有所发展或是发生改变。
一个需求下来要提供给前端十几个 api ，以前用 swagger 一般都是先写 controller ，写完前端就能开发了，现在是定义完接口还得花半天时间写文档接口，这个过程真的无比痛苦，每写一个接口都得重复以下步骤：
1 、复制接口 url
2 、切换到 postman 写 request body
3 、在接口 retrun 造的假数据，要是返回的数据结构简单还好，要是那种各种嵌套对象和 list 的结构那就更恶心了
4 、发起请求，把 url 、请求 json 和返回 json copy 到文档上
5 、写返回字段的备注
这五步 每一步都是折磨，搞得每次开发干这种搬砖活就要搞半天
1 、复制接口 url
2 、切换到 postman 写 request body
3 、在接口 retrun 造的假数据，要是返回的数据结构简单还好，要是那种各种嵌套对象和 list 的结构那就更恶心了
4 、发起请求，把 url 、请求 json 和返回 json copy 到文档上
5 、写返回字段的备注
这五步 每一步都是折磨，搞得每次开发干这种搬砖活就要搞半天
 | 1 rxswift 2022-08-11 19:55:17 +08:00 有什么好办法吗 |
 | 2 pigmen 2022-08-11 19:56:05 +08:00 那为啥不用 swagger 呢？ |
 | 3 BeautifulSoap 2022-08-11 19:58:20 +08:00 via Android 还有人手写 swagger 的？。。。。。 就算你项目没开始写代码，先随便用个框架简单定义好空的 controller 还有 DTO ，直接生成 swagger 不就好了，不至于手写 swagger |
 | 4 voidmnwzp OP @BeautifulSoap 之前一家是 swagger 很方便 这家不让用 swagger 必须手写 api 文档 |
 | 5 issakchill 2022-08-11 21:10:36 +08:00 搞个 yapi 无侵入的输出吧 手写也太累了吧 |
 | 6 freebird1994 2022-08-11 21:27:02 +08:00 via Android yapi 手填文档，apipost 和 postman 一样做接口自测，可以根据返回的数据结构生成文档（自己写注释），应该都比你现在效率高些而且好维护些 |
 | 7 AV1 2022-08-11 21:31:54 +08:00 via Android 我觉得你对接的前端同事面对这样的文档，也会跟你一样难受。 我觉得你们可以学一下 typescript 的 interface 语法，用来当作对象字段描述语言，表达那些复杂的对象会方便一些，前段同事也能方便对接字段。 |
 | 8 zhuangzhuang1988 2022-08-11 21:35:48 +08:00  10 postman 肯定是要走一遍的 我前端 接过 postman 没走一遍的 后端 api 每次都有 api 问题, 一问后端, 自己都没测试过. |
 | 9 Vegetable 2022-08-11 21:41:10 +08:00 ...写空 Controller 先生成文档不行吗 |
 | 10 winglight2016 2022-08-11 22:16:58 +08:00 swagger 也支持自定义模板的，为啥不自己定制一下？实在不行自己解析一下 api json ，用模板生成一下 |
 | 11 jack778 2022-08-11 22:27:06 +08:00 1 apifox 自动生成 api 在线共享,爽的一比,打灰机 |
 | 12 v2eb 2022-08-11 22:44:41 +08:00 via Android 有根据 javadoc 生成文档的。smart-doc |
 | 13 hsuyeung 2022-08-11 22:55:27 +08:00 knife4j 的文档导出功能，导出成 word 应该可以吧，我试了下，感觉格式还行 |
 | 15 dingyaguang117 2022-08-11 23:04:06 +08:00 stoplight 了解一下 |
 | 16 Leoooooo 2022-08-11 23:12:48 +08:00 花一天时间写个自动化工具，只需要手动补充文档释义。节省未来一大半精力，还有成就感。 |
 | 17 BearCookie 2022-08-11 23:26:49 +08:00 有啥现成好法子不 |
 | 18 dumbass 2022-08-11 23:49:57 +08:00 via iPhone 对接的前端大概也很难受，现在做的项目接口文档用的 word ，看着很难受，而且没有用等宽字体 l 和 I 都分不清，只好全局替换成等宽字体。 |
 | 19 iseki 2022-08-12 00:32:53 +08:00 via Android 要么写代码生成文档，要么写文档生成代码，既写代码又写文档这的确烦人，时间一久就容易代码文档对不上 |
 | 20 kkeep 2022-08-12 01:08:17 +08:00 via Android 我有解决办法，半夜起来加班，在前端开始做之前，接口就 ready |
 | 21 MarioLuo 2022-08-12 07:53:38 +08:00 via Android 如果是用的 spring ，可以用这个 Idea 插件，从标准 Java doc 生成代码: https://github.com/jetplugins/yapix |
 | 22 NPC666 2022-08-12 08:19:35 +08:00 via Android 我们是手写 swagger ，一个 yml 文件上万行，复制粘贴的时候 IDE 都要卡一会儿 |
 | 23 xiao109 2022-08-12 08:30:25 +08:00 swagger 连他亲爹都放弃了吧 |
 | 24 bitmin 2022-08-12 08:31:11 +08:00 via Android yapi github 的 readme 上推荐了一些 idea 插件，我最近在用 easy-yapi 这个插件。因为写着 easy 就点开看了。代码无侵入，通过 Javadoc API 生成文档。可以导出到 yapi postman 等。还提供了一些增强的配置，可以配置回调。 我打算提交代码到 gitlab 的时候自动执行工具生成导出到 yapi ，有没有这样的工具？ |
 | 25 94 2022-08-12 08:43:00 +08:00 考虑一下 yapi 这种可以生成接口文档的东西？ |
 | 26 leeUp 2022-08-12 09:01:18 +08:00 可以自己本地用 swagger 生成，然后用 postman 导入，这样就可以了 |
 | 27 liuzhihang 2022-08-12 09:07:01 +08:00 via iPhone 1 试试我写的 idea 插件: Doc View |
 | 28 littleMouse 2022-08-12 09:22:40 +08:00 为啥我们是前端写 api 文档啊，好痛苦┭┮┭┮ |
 | 29 C603H6r18Q1mSP9N 写完自己不测试一遍？ 没有测试测接口？ |
 | 30 xuanbg 2022-08-12 09:30:07 +08:00 手写 API 文档就是在模版上做几道填空题嘛，好写的很！而且我都是先把文档写好再开始写代码的。 |
 | 31 still97 2022-08-12 09:37:43 +08:00 @xuanbg 有没有可能，你的结构都很简单？我这一份简单的报告三四百行返回数据，各种嵌套数据格式，真没感觉到你说的这种简单。 |
 | 32 cccssss 2022-08-12 09:39:31 +08:00 曾经我也很痛苦，然后我花了大半天用 javaparser-core 写了一个获取 java doc 的小脚本就搞定了，一共 400 行代码 |
 | 33 xuboying 2022-08-12 09:41:37 +08:00 手工写的文档用户一般是不信任的。。。。 |
 | 35 aboat365 2022-08-12 09:45:28 +08:00 1 对于不让使用 Swagger 、不让使用 Lombok 、不让使用 IDEA ，不让使用方便程序开发，而又讲不出有力禁止理由的规定，都是耍流氓。程序的本质是什么？就是解放劳动力，提高生产力，把手动工作，编排成机器自动的工作。一切程序可以自动替代的，都应该由程序来做！ |
 | 36 alen0206 2022-08-12 10:04:36 +08:00 如果是用的 Yapi 可以用 YapiUpload 插件 接口定义写完就能上传 |
 | 37 MarioLuo 2022-08-12 10:30:55 +08:00 1 @bitmin smart-doc maven 插件 自己扩展下上传到 yapi 可以实现，但是有个问题，多分支开发怎么弄，yapi 本身的文档管理功能没有多分支，多版本的概念 |
 | 38 CodeCodeStudy 2022-08-12 10:37:39 +08:00 做完不测试吗，测试的话 postman 的流程也要走一遍吧 |
 | 39 NoKey 2022-08-12 10:40:21 +08:00 你完全可以搞个 idea ，然后在里面写 controller 及各参数，要么用 swagger ，要么 idea 加一些插件，能生成 request body 的 json 结构，写文档也快。手写 api ，也不是完全不写代码，比如要 uml 图，你真的手写去画么？ idea 先写一些伪代码，自动生成了复制啊 |
 | 40 RainCats 2022-08-12 10:43:55 +08:00 用模板技术去生成，提前写好模板就好了 |
 | 41 shalk 2022-08-12 10:47:56 +08:00 自己想办法生成一下，再稍微改改 |
 | 42 18601294989 2022-08-12 10:51:28 +08:00 swagger 导出到 postman 就好了吧 |
 | 43 lpbname777 2022-08-12 10:57:40 +08:00 @zhuangzhuang1988 雾草！后端接口盲写 同感 |
 | 44 aicfe 022-08-12 11:26:36 +08:00 我用 yapi + idea 上安装 easyYapi 插件 一键导出 还能给前端 mock |
| 45 zhuangzhuang1988 2022-08-12 11:26:42 +08:00 via Android @lpbname777 遇到太多了，前端当测试，最基础的数据都过不了 |
 | 46 edward1987 2022-08-12 11:27:40 +08:00 无论输出是什么,都要自动化 |
 | 47 xuxuzhaozhao 2022-08-12 13:18:43 +08:00 了解一下 ApiPost ，爽得呀丕 |
 | 48 potatowish 2022-08-12 13:43:37 +08:00 via iPhone 不让用 swagger 估计是侵入代码层了，考虑下无侵入的方式，比如说 smart-doc ，或者是基于单元测试的，sping rest doc 离线文档 |
 | 49 nothingistrue 2022-08-12 13:53:23 +08:00 目测你在移动、联通系统集成或者类似这样的企业里面做外包，或者是对日外包。死板的 CMMI 规范，一行代码一百页文档，自己不想干就让外包的人干。 |
 | 50 lllllliiii 2022-08-12 14:14:44 +08:00 可以试试 easy yapi 导出 md 文档 |
 | 51 StarkWhite 2022-08-12 14:19:20 +08:00 fb 的 graphql 了解下，文档不用写了 https://v2ex.com/t/589138?p=2#reply137 |
| 52 voidmnwzp OP @nothingistrue 并不是 是个 to c 互联网企业 反而之前是在做电信项目的公司用的 swagger |
 | 53 hetal 2022-08-12 15:48:26 +08:00 protobuf 不香么，配合 doc 工具自动生成 api 文档，再加一个 restful 网关就行了 |
 | 54 tiedan 2022-08-12 17:08:50 +08:00 我的关注点是一个需求十几个新 api 。。。 这么恐怖吗 |
 | 55 gzlixiaochao555 2022-08-12 17:26:30 +08:00 可以试试 Eolink ，通过 swagger.json 直接生成接口文档，支持在线测试 |
 | 56 watzds 2022-08-12 18:13:06 +08:00 IDEA 装 EasyApi 插件，写完 Controller 能直接同步到 yapi, postman 等地方，很方便啊 |
 | 57 pengtdyd 2022-08-12 21:12:02 +08:00 S 13 的技术管理，就是有这些奇葩的事情。 |
 | 58 ClarkAbe 2022-08-13 18:33:31 +08:00 via Android 我司也是我这边五个大模块将近四百个接口前几天主管说用手写文档还要一个月内开发完....我直接就怼回去了 |
| 60 xuanbg 2022-08-15 11:29:46 +08:00 @still97 对象嵌套不是很正常的嘛，问题是你要怎么去描述。我就是把所有对象都用表格描述，表格里面有一列叫类型，那么某个字段该是什么类型就加个跳转指向那个类型的表格就好了呀。 一般这个没人看的，因为我提供了示例数据，包括入参和返回数据。前端看到返回数据的示例，就知道接口返回是什么。只要照抄我提供的参数，就能返回期望的数据。 |
 | 62 ricebna 2023-10-14 22:35:22 +08:00 对于接口文档的编写， 我觉得用任何工具都会有效率耗损。包括 yapi ，postman ，还有注释类的 swagger 。 接口文档特别是内部用的并且是前端用的，95%的情况就是一个简单的输出与输入，主要工作是描述清楚字段结构，主要目的是与前端达成沟通以及存档的作用，并不需要多么标准化。 而各种工具，无论是界面类的还是注释自动转换类的， 都需要遵照特定规范，按要求去填写。 点击一个输入框或是写上特定注释标记都需要额外的时间与心智消耗，这些精准规范其实没必要, 并且他们(特别是国产工具)都经不起时间的变化, 另外维护更新工作也是一个反人性大家都不想做的事情。 所以我在想在写文档的效率方面， 直接用最简单的文本是最方便的，直接在代码编辑器写注释文本，不需要遵照特定注释规范, 特别是输出参数比较多, 层级也多, 直接用所见即所得的 json 文本本身做为描述是最简单的。无需担心格式出错, 维护更新也在相同的地方, 没有割裂感. 并且他们的经得起时间的沉淀 (越简单的东西, 他们的存在度和稳定性就越高, 日后你想要转换成任何文档形式都可以. 这也是我对于笔记应用的一个观念转变: 从印象笔记到后来直接用 vscode 写 md, 到现在 md 只不过是一个文件后缀而实际很少用它的语法了, 而同步功能直接用谷歌云盘同步目录, git 不定期备份. 大道至简) 然后把我们写得不那么标准的简化注释用 ChatGPT 转换成勉强标准的结构化文档，它就适合做这类不精准的东西，还有纠错能力。 我试过了，它转换成的 postman 导入文件居然是对的，我还担心这种事情它一般会出错，不过凡涉及代码的东西最好不用，有时出错给它排错的时间不值。 [Imgur](  ) |
Select Language