手写 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 条回复
shalk
2022 年 8 月 12 日
自己想办法生成一下，再稍微改改
18601294989
2022 年 8 月 12 日
swagger 导出到 postman 就好了吧
lpbname777
2022 年 8 月 12 日
@zhuangzhuang1988 雾草！后端接口盲写 同感
aicfe
2022 年 8 月 12 日
我用 yapi + idea 上安装 easyYapi 插件 一键导出 还能给前端 mock
zhuangzhuang1988
2022 年 8 月 12 日
@lpbname777 遇到太多了，前端当测试，最基础的数据都过不了
edward1987
2022 年 8 月 12 日
无论输出是什么,都要自动化
xuxuzhaozhao
2022 年 8 月 12 日
了解一下 ApiPost ，爽得呀丕
potatowish
2022 年 8 月 12 日
不让用 swagger 估计是侵入代码层了，考虑下无侵入的方式，比如说 smart-doc ，或者是基于单元测试的，sping rest doc 离线文档
nothingistrue
2022 年 8 月 12 日
目测你在移动、联通系统集成或者类似这样的企业里面做外包，或者是对日外包。死板的 CMMI 规范，一行代码一百页文档，自己不想干就让外包的人干。
lllllliiii
2022 年 8 月 12 日
可以试试 easy yapi 导出 md 文档
StarkWhite
2022 年 8 月 12 日
fb 的 graphql 了解下，文档不用写了
https://v2ex.com/t/589138?p=2#reply137
voidmnwzp
2022 年 8 月 12 日
@nothingistrue 并不是 是个 to c 互联网企业 反而之前是在做电信项目的公司用的 swagger
hetal
2022 年 8 月 12 日
protobuf 不香么，配合 doc 工具自动生成 api 文档，再加一个 restful 网关就行了
tiedan
2022 年 8 月 12 日
我的关注点是一个需求十几个新 api 。。。 这么恐怖吗
gzlixiaochao555
2022 年 8 月 12 日
可以试试 Eolink ，通过 swagger.json 直接生成接口文档，支持在线测试
watzds
2022 年 8 月 12 日
IDEA 装 EasyApi 插件，写完 Controller 能直接同步到 yapi, postman 等地方，很方便啊
pengtdyd
2022 年 8 月 12 日
S 13 的技术管理，就是有这些奇葩的事情。
ClarkAbe
2022 年 8 月 13 日
我司也是我这边五个大模块将近四百个接口前几天主管说用手写文档还要一个月内开发完....我直接就怼回去了
voidmnwzp
2022 年 8 月 15 日
@ClarkAbe 这种还不如跑了
xuanbg
2022 年 8 月 15 日
@still97 对象嵌套不是很正常的嘛，问题是你要怎么去描述。我就是把所有对象都用表格描述，表格里面有一列叫类型，那么某个字段该是什么类型就加个跳转指向那个类型的表格就好了呀。
一般这个没人看的，因为我提供了示例数据，包括入参和返回数据。前端看到返回数据的示例，就知道接口返回是什么。只要照抄我提供的参数，就能返回期望的数据。

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

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

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

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

© 2021 V2EX