手写 api 文档写得想跑路了

2022 年 8 月 11 日
 voidmnwzp
一个需求下来要提供给前端十几个 api ，以前用 swagger 一般都是先写 controller ，写完前端就能开发了，现在是定义完接口还得花半天时间写文档接口，这个过程真的无比痛苦，每写一个接口都得重复以下步骤：
1 、复制接口 url
2 、切换到 postman 写 request body
3 、在接口 retrun 造的假数据，要是返回的数据结构简单还好，要是那种各种嵌套对象和 list 的结构那就更恶心了
4 、发起请求，把 url 、请求 json 和返回 json copy 到文档上
5 、写返回字段的备注
这五步 每一步都是折磨，搞得每次开发干这种搬砖活就要搞半天
9985 次点击
所在节点    程序员
62 条回复
MarioLuo
2022 年 8 月 12 日
如果是用的 spring ，可以用这个 Idea 插件，从标准 Java doc 生成代码: https://github.com/jetplugins/yapix
NPC666
2022 年 8 月 12 日
我们是手写 swagger ，一个 yml 文件上万行，复制粘贴的时候 IDE 都要卡一会儿😅
xiao109
2022 年 8 月 12 日
swagger 连他亲爹都放弃了吧
bitmin
2022 年 8 月 12 日
yapi github 的 readme 上推荐了一些 idea 插件，我最近在用 easy-yapi 这个插件。因为写着 easy 就点开看了。代码无侵入，通过 Javadoc API 生成文档。可以导出到 yapi postman 等。还提供了一些增强的配置，可以配置回调。

我打算提交代码到 gitlab 的时候自动执行工具生成导出到 yapi ，有没有这样的工具？
94
2022 年 8 月 12 日
考虑一下 yapi 这种可以生成接口文档的东西？
leeUp
2022 年 8 月 12 日
可以自己本地用 swagger 生成，然后用 postman 导入，这样就可以了
liuzhihang
2022 年 8 月 12 日
试试我写的 idea 插件: Doc View
littleMouse
2022 年 8 月 12 日
为啥我们是前端写 api 文档啊，好痛苦┭┮﹏┭┮
C603H6r18Q1mSP9N
2022 年 8 月 12 日
写完自己不测试一遍？
没有测试测接口？
xuanbg
2022 年 8 月 12 日
手写 API 文档就是在模版上做几道填空题嘛，好写的很！而且我都是先把文档写好再开始写代码的。
still97
2022 年 8 月 12 日
@xuanbg 有没有可能，你的结构都很简单？我这一份简单的报告三四百行返回数据，各种嵌套数据格式，真没感觉到你说的这种简单。
cccssss
2022 年 8 月 12 日
曾经我也很痛苦，然后我花了大半天用 javaparser-core 写了一个获取 java doc 的小脚本就搞定了，一共 400 行代码
xuboying
2022 年 8 月 12 日
手工写的文档用户一般是不信任的。。。。
xuboying
2022 年 8 月 12 日
@xuboying #33 文档-> API 文档
aboat365
2022 年 8 月 12 日
对于不让使用 Swagger 、不让使用 Lombok 、不让使用 IDEA ，不让使用方便程序开发，而又讲不出有力禁止理由的规定，都是耍流氓。程序的本质是什么？就是解放劳动力，提高生产力，把手动工作，编排成机器自动的工作。一切程序可以自动替代的，都应该由程序来做！
alen0206
2022 年 8 月 12 日
如果是用的 Yapi 可以用 YapiUpload 插件 接口定义写完就能上传
MarioLuo
2022 年 8 月 12 日
@bitmin smart-doc maven 插件 自己扩展下上传到 yapi 可以实现，但是有个问题，多分支开发怎么弄，yapi 本身的文档管理功能没有多分支，多版本的概念
CodeCodeStudy
2022 年 8 月 12 日
做完不测试吗，测试的话 postman 的流程也要走一遍吧
NoKey
2022 年 8 月 12 日
你完全可以搞个 idea ，然后在里面写 controller 及各参数，要么用 swagger ，要么 idea 加一些插件，能生成 request body 的 json 结构，写文档也快。手写 api ，也不是完全不写代码，比如要 uml 图，你真的手写去画么？ idea 先写一些伪代码，自动生成了复制啊
RainCats
2022 年 8 月 12 日
用模板技术去生成，提前写好模板就好了

这是一个专为移动设备优化的页面（即为了让你能够在 Google 搜索结果里秒开这个页面），如果你希望参与 V2EX 社区的讨论，你可以继续到 V2EX 上打开本讨论主题的完整版本。

https://study.congcong.us/t/872274

V2EX 是创意工作者们的社区，是一个分享自己正在做的有趣事物、交流想法，可以遇见新朋友甚至新机会的地方。

V2EX is a community of developers, designers and creative people.

© 2021 V2EX