手写 api 文档写得想跑路了

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

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

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

https://tanronggui.xyz/t/872274

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

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

© 2021 V2EX