手写 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

[MarioLuo]

如果是用的 spring ，可以用这个 Idea 插件，从标准 Java doc 生成代码: https://github.com/jetplugins/yapix

[NPC666]

我们是手写 swagger ，一个 yml 文件上万行，复制粘贴的时候 IDE 都要卡一会儿😅

[xiao109]

swagger 连他亲爹都放弃了吧

[bitmin]

yapi github 的 readme 上推荐了一些 idea 插件，我最近在用 easy-yapi 这个插件。因为写着 easy 就点开看了。代码无侵入，通过 Javadoc API 生成文档。可以导出到 yapi postman 等。还提供了一些增强的配置，可以配置回调。

我打算提交代码到 gitlab 的时候自动执行工具生成导出到 yapi ，有没有这样的工具？

[dfkjgklfdjg]

考虑一下 yapi 这种可以生成接口文档的东西？

[leeUp]

可以自己本地用 swagger 生成，然后用 postman 导入，这样就可以了

[liuzhihang]

试试我写的 idea 插件: Doc View

[littleMouse]

为啥我们是前端写 api 文档啊，好痛苦┭┮﹏┭┮

[C603H6r18Q1mSP9N]

写完自己不测试一遍？
没有测试测接口？

[xuanbg]

手写 API 文档就是在模版上做几道填空题嘛，好写的很！而且我都是先把文档写好再开始写代码的。

[still97]

@xuanbg 有没有可能，你的结构都很简单？我这一份简单的报告三四百行返回数据，各种嵌套数据格式，真没感觉到你说的这种简单。

[cccssss]

曾经我也很痛苦，然后我花了大半天用 javaparser-core 写了一个获取 java doc 的小脚本就搞定了，一共 400 行代码

[xuboying]

手工写的文档用户一般是不信任的。。。。

[xuboying]

@xuboying #33 文档-> API 文档

[aboat365]

对于不让使用 Swagger 、不让使用 Lombok 、不让使用 IDEA ，不让使用方便程序开发，而又讲不出有力禁止理由的规定，都是耍流氓。程序的本质是什么？就是解放劳动力，提高生产力，把手动工作，编排成机器自动的工作。一切程序可以自动替代的，都应该由程序来做！

[alen0206]

如果是用的 Yapi 可以用 YapiUpload 插件 接口定义写完就能上传

[MarioLuo]

@bitmin smart-doc maven 插件 自己扩展下上传到 yapi 可以实现，但是有个问题，多分支开发怎么弄，yapi 本身的文档管理功能没有多分支，多版本的概念

[CodeCodeStudy]

做完不测试吗，测试的话 postman 的流程也要走一遍吧

[NoKey]

你完全可以搞个 idea ，然后在里面写 controller 及各参数，要么用 swagger ，要么 idea 加一些插件，能生成 request body 的 json 结构，写文档也快。手写 api ，也不是完全不写代码，比如要 uml 图，你真的手写去画么？ idea 先写一些伪代码，自动生成了复制啊

[RainCats]

用模板技术去生成，提前写好模板就好了

[shalk]

自己想办法生成一下，再稍微改改

[18601294989]

swagger 导出到 postman 就好了吧

[lpbname777]

@zhuangzhuang1988 雾草！后端接口盲写 同感

[aicfe]

我用 yapi + idea 上安装 easyYapi 插件 一键导出 还能给前端 mock

[zhuangzhuang1988]

@lpbname777 遇到太多了，前端当测试，最基础的数据都过不了

[edward1987]

无论输出是什么,都要自动化

[xuxuzhaozhao]

了解一下 ApiPost ，爽得呀丕

[potatowish]

不让用 swagger 估计是侵入代码层了，考虑下无侵入的方式，比如说 smart-doc ，或者是基于单元测试的，sping rest doc 离线文档

[nothingistrue]

目测你在移动、联通系统集成或者类似这样的企业里面做外包，或者是对日外包。死板的 CMMI 规范，一行代码一百页文档，自己不想干就让外包的人干。

[fzdwx]

可以试试 easy yapi 导出 md 文档

[StarkWhite]

fb 的 graphql 了解下，文档不用写了
https://v2ex.com/t/589138?p=2#reply137

[voidmnwzp]

@nothingistrue 并不是 是个 to c 互联网企业 反而之前是在做电信项目的公司用的 swagger

[hetal]

protobuf 不香么，配合 doc 工具自动生成 api 文档，再加一个 restful 网关就行了

[tiedan]

我的关注点是一个需求十几个新 api 。。。 这么恐怖吗

[gzlixiaochao555]

可以试试 Eolink ，通过 swagger.json 直接生成接口文档，支持在线测试

[watzds]

IDEA 装 EasyApi 插件，写完 Controller 能直接同步到 yapi, postman 等地方，很方便啊

[pengtdyd]

S 13 的技术管理，就是有这些奇葩的事情。

[ClarkAbe]

我司也是我这边五个大模块将近四百个接口前几天主管说用手写文档还要一个月内开发完....我直接就怼回去了

[voidmnwzp]

@ClarkAbe 这种还不如跑了

[xuanbg]

@still97 对象嵌套不是很正常的嘛，问题是你要怎么去描述。我就是把所有对象都用表格描述，表格里面有一列叫类型，那么某个字段该是什么类型就加个跳转指向那个类型的表格就好了呀。
一般这个没人看的，因为我提供了示例数据，包括入参和返回数据。前端看到返回数据的示例，就知道接口返回是什么。只要照抄我提供的参数，就能返回期望的数据。

[ClarkAbe]

@voidmnwzp 我也想但是小城找新的太麻烦了

[ricebna]

对于接口文档的编写， 我觉得用任何工具都会有效率耗损。包括 yapi ，postman ，还有注释类的 swagger 。
接口文档特别是内部用的并且是前端用的，95%的情况就是一个简单的输出与输入，主要工作是描述清楚字段结构，主要目的是与前端达成沟通以及存档的作用，并不需要多么标准化。
而各种工具，无论是界面类的还是注释自动转换类的， 都需要遵照特定规范，按要求去填写。
点击一个输入框或是写上特定注释标记都需要额外的时间与心智消耗，这些精准规范其实没必要, 并且他们(特别是国产工具)都经不起时间的变化, 另外维护更新工作也是一个反人性大家都不想做的事情。

所以我在想在写文档的效率方面， 直接用最简单的文本是最方便的，直接在代码编辑器写注释文本，不需要遵照特定注释规范, 特别是输出参数比较多, 层级也多, 直接用所见即所得的 json 文本本身做为描述是最简单的。无需担心格式出错, 维护更新也在相同的地方, 没有割裂感. 并且他们的经得起时间的沉淀 (越简单的东西, 他们的存在度和稳定性就越高, 日后你想要转换成任何文档形式都可以. 这也是我对于笔记应用的一个观念转变: 从印象笔记到后来直接用 vscode 写 md, 到现在 md 只不过是一个文件后缀而实际很少用它的语法了, 而同步功能直接用谷歌云盘同步目录, git 不定期备份. 大道至简)

然后把我们写得不那么标准的简化注释用 ChatGPT 转换成勉强标准的结构化文档，它就适合做这类不精准的东西，还有纠错能力。
我试过了，它转换成的 postman 导入文件居然是对的，我还担心这种事情它一般会出错，不过凡涉及代码的东西最好不用，有时出错给它排错的时间不值。
[Imgur]( )