手写 api 文档写得想跑路了

[voidmnwzp]

一个需求下来要提供给前端十几个 api ，以前用 swagger 一般都是先写 controller ，写完前端就能开发了，现在是定义完接口还得花半天时间写文档接口，这个过程真的无比痛苦，每写一个接口都得重复以下步骤：
1 、复制接口 url
2 、切换到 postman 写 request body
3 、在接口 retrun 造的假数据，要是返回的数据结构简单还好，要是那种各种嵌套对象和 list 的结构那就更恶心了
4 、发起请求，把 url 、请求 json 和返回 json copy 到文档上
5 、写返回字段的备注
这五步 每一步都是折磨，搞得每次开发干这种搬砖活就要搞半天

[rxswift]

有什么好办法吗

[pigmen]

那为啥不用 swagger 呢？

[BeautifulSoap]

还有人手写 swagger 的？。。。。。
就算你项目没开始写代码，先随便用个框架简单定义好空的 controller 还有 DTO ，直接生成 swagger 不就好了，不至于手写 swagger

[voidmnwzp]

@BeautifulSoap 之前一家是 swagger 很方便 这家不让用 swagger 必须手写 api 文档

[issakchill]

搞个 yapi 无侵入的输出吧 手写也太累了吧

[freebird1994]

yapi 手填文档，apipost 和 postman 一样做接口自测，可以根据返回的数据结构生成文档（自己写注释），应该都比你现在效率高些而且好维护些

[DOLLOR]

我觉得你对接的前端同事面对这样的文档，也会跟你一样难受。
我觉得你们可以学一下 typescript 的 interface 语法，用来当作对象字段描述语言，表达那些复杂的对象会方便一些，前段同事也能方便对接字段。

[zhuangzhuang1988]

postman 肯定是要走一遍的
我前端 接过 postman 没走一遍的 后端 api
每次都有 api 问题, 一问后端, 自己都没测试过.

[Vegetable]

...写空 Controller 先生成文档不行吗

[winglight2016]

swagger 也支持自定义模板的，为啥不自己定制一下？实在不行自己解析一下 api json ，用模板生成一下

[jack778]

apifox 自动生成 api 在线共享,爽的一比,打灰机

[v2eb]

有根据 javadoc 生成文档的。smart-doc

[hsuyeung]

knife4j 的文档导出功能，导出成 word 应该可以吧，我试了下，感觉格式还行

[hsuyeung]

@hsuyeung 也有 HTML 、Markdown 、OpenAPI 格式的

[dingyaguang117]

stoplight 了解一下

[Leoooooo]

花一天时间写个自动化工具，只需要手动补充文档释义。节省未来一大半精力，还有成就感。

[neochen13]

有啥现成好法子不

[bojackhorseman]

对接的前端大概也很难受，现在做的项目接口文档用的 word ，看着很难受，而且没有用等宽字体 l 和 I 都分不清😅，只好全局替换成等宽字体。

[iseki]

要么写代码生成文档，要么写文档生成代码，既写代码又写文档这的确烦人，时间一久就容易代码文档对不上

[kkeep]

我有解决办法，半夜起来加班，在前端开始做之前，接口就 ready