手写 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 条回复
rxswift
2022 年 8 月 11 日
有什么好办法吗
pigmen
2022 年 8 月 11 日
那为啥不用 swagger 呢？
BeautifulSoap
2022 年 8 月 11 日
还有人手写 swagger 的？。。。。。
就算你项目没开始写代码，先随便用个框架简单定义好空的 controller 还有 DTO ，直接生成 swagger 不就好了，不至于手写 swagger
voidmnwzp
2022 年 8 月 11 日
@BeautifulSoap 之前一家是 swagger 很方便 这家不让用 swagger 必须手写 api 文档
issakchill
2022 年 8 月 11 日
搞个 yapi 无侵入的输出吧 手写也太累了吧
freebird1994
2022 年 8 月 11 日
yapi 手填文档，apipost 和 postman 一样做接口自测，可以根据返回的数据结构生成文档（自己写注释），应该都比你现在效率高些而且好维护些
AV1
2022 年 8 月 11 日
我觉得你对接的前端同事面对这样的文档，也会跟你一样难受。
我觉得你们可以学一下 typescript 的 interface 语法，用来当作对象字段描述语言，表达那些复杂的对象会方便一些，前段同事也能方便对接字段。
zhuangzhuang1988
2022 年 8 月 11 日
postman 肯定是要走一遍的
我前端 接过 postman 没走一遍的 后端 api
每次都有 api 问题, 一问后端, 自己都没测试过.
Vegetable
2022 年 8 月 11 日
...写空 Controller 先生成文档不行吗
winglight2016
2022 年 8 月 11 日
swagger 也支持自定义模板的，为啥不自己定制一下？实在不行自己解析一下 api json ，用模板生成一下
jack778
2022 年 8 月 11 日
apifox 自动生成 api 在线共享,爽的一比,打灰机
v2eb
2022 年 8 月 11 日
有根据 javadoc 生成文档的。smart-doc
hsuyeung
2022 年 8 月 11 日
knife4j 的文档导出功能，导出成 word 应该可以吧，我试了下，感觉格式还行
hsuyeung
2022 年 8 月 11 日
@hsuyeung 也有 HTML 、Markdown 、OpenAPI 格式的
dingyaguang117
2022 年 8 月 11 日
stoplight 了解一下
Leoooooo
2022 年 8 月 11 日
花一天时间写个自动化工具，只需要手动补充文档释义。节省未来一大半精力，还有成就感。
BearCookie
2022 年 8 月 11 日
有啥现成好法子不
dumbass
2022 年 8 月 11 日
对接的前端大概也很难受，现在做的项目接口文档用的 word ，看着很难受，而且没有用等宽字体 l 和 I 都分不清😅，只好全局替换成等宽字体。
iseki
2022 年 8 月 12 日
要么写代码生成文档，要么写文档生成代码，既写代码又写文档这的确烦人，时间一久就容易代码文档对不上
kkeep
2022 年 8 月 12 日
我有解决办法，半夜起来加班，在前端开始做之前，接口就 ready

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

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

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

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

© 2021 V2EX