后端不写 api 文档怎么办， V 友们究竟是怎么解决的

[unt]

后端只写 swagger,那玩意儿真的是狗都不看，为什么能设计得如此丑陋，有没有写得好的 swagger 让我看看，看是我们后端的问题还是这个工具的问题。

像下图这种文档只能手码吗，有工具吗

[owen800q]

叫他直接给 postman collection, 自己生成 html 文档
https://github.com/karthiks3000/postman-doc-gen

[bojackhorseman]

https://github.com/acacode/swagger-typescript-api
我都是用这个库根据 swagger.json 生成请求文件，支持 axios 模板。
后端手写文档的我才想骂人了，改了接口也不同步。swagger 方便的一批。

[owen800q]

@owen800q 我日常工作就是這樣做的，現實是後端不可能寫文檔，至少我沒見過會給文檔的後端開發

[lei2j]

swagger 写的多方便啊，参数变了立马同步

[SuperManNoPain]

现在不会有人特地去手写的，都是写备注配合插件自动同步或者直接 swagger 了，

[LeegoYih]

Swagger 只是一个 UI 啊，它是基于 OpenAPI 规范实现的，有很多工具可以通过 OpenAPI 反向生成代码，比如： https://github.com/alibaba/pont

[Vegetable]

后端给了 Swagger 自己嫌丑？我冒昧的问一句，市面上有但凡一个流行的文档工具不支持导入 Swagger 吗？

[dayeye2006199]

都给了 OAS 了，想要长什么样自己挑个工具就行

[zachlhb]

这个应该找公司规范，指定统一的文档规范，总之我们是不用 swagger 的，我们用 yapi 自己建了一套文档平台，就算你项目里用了 swagger ，也要整理到 yapi 上面

[MozzieW]

"后端不写 api 文档怎么办"
"后端只写 swagger"

你自己看着办

[sjn9588]

swagger 丑陋的意思是？ yml 可读性差？还是说 swagger ui 丑啊。

[IvanLi127]

swagger 可以在代码里给它加各种请求示例，加各类的响应代表的含义，每个字段都能写备注，能标记接口需要的登录凭据，还能在页面上直接发请求测试，肯定够用了。

[tsanie]

不喜欢 swagger ui 的我推荐个 redoc

[Imindzzz]

https://yapi.pro

[qinfengge]

idea 中有 APIfox 的插件，可以直接同步

[me1onsoda]

那就是你这逼前端的问题，swagger 可以直接调试，不比文档高效？接口变动手动维护文档？

[lihexinkai]

可以用 knif4j ，swagger 确实没法看，不过对于后端来说他肯定不想搞的，看你本事了，搞好关系，或者 pua 他😎

[cnbattle]

看不到图，

推测： 矛盾点 可能是后端用的 swagger 用的也不标准，生成出来的文档不清晰，导致看不懂，

更多还是人或沟通问题 不是工具问题

[fumichael]

@bojackhorseman #2 swaggerui 有些版本是挺难用的
我是装油猴脚本辅助复制的
你这个方案貌似不错

[EchoAI]

有可能 OP 想问的是：后端只给一个 swagger 里面有很多的字段，也不表明字段的含义，让你去猜这些字段到底是什么意思。哪些字段是必填参数，哪些是可选参数。参数都有哪些可选的选项，参数类型明明是 int ，实测接口下来确实 string 。而且一股脑的把所有的字段都给你了，还有许多字段是在某一个字段为特定值的时候才会有。这些后端统统不说。

[unt]

@EchoAI #20 是的是的，你完全懂我。我想要的是 0 沟通，全靠文档对接。现在沟通成本太高了

[unt]

@EchoAI #20 而且我们这边对于嵌套对象的注释也没有，只有第一层对象属性的注释

[ruoxie]

sw 看起来确实费劲，我都是导到 yapi 里

[HelloWorld556]

我前后端自己写，没这些烦恼。你的图片看不到啊 萤石接口.png

[PlsDontStop]

你倒是给我们看看怎么个丑陋法啊

[LavaC]

swagger 能不能看全看后端用不用心，有的别说注释了，参数都写不全，还有文档写 query 传数组的。这时候过去跟后端儒雅随和一番是最有效的解决方法。

[Desiree]

最恶心的是，有文档了，字段没有注释...

[wxw752]

那是你们后端 swagger 注解写的不规范，直接骂他就行了，这个锅 swagger 可不能背。

[fumichael]

楼主的图，微博图床现在又不能直接访问了？
https://i0.wp.com/tva1.sinaimg.cn/large/aa9984degy1hg9jpuq94oj20wi17s447.jpg

[InDom]

作为一个后端，说真的确实不愿意专门去写文档，如果非要提供文档，我会想办法自动化生成 md 然后再转成 word 或 html 提交。

但是，无论使用 swagger 还是 postman ，最少得有一个地方能有完整的，随时更新且应该尽可能正确带有详细注释的接口说明。

至于好不好看，老子才不管呢，又不是不能用。你不是前端嘛，嫌不好看可以自己调样式啊。

所以，个人结论：后端提供文档字段方面的不完整，必须后端给。

至于界面不好看，能看就行，不行自己改。

至于不好使，这个问题应该前后端沟通，选择对双方都好的，或者是能相互转换的。

[aogg]

就算是 swagger 不好用，也不是你前端赖后端的原因，逼事真多，前端普片的菜和有问题赖后端

[MENGKE]

评论区后端集体破防

[BG7ZAG]

直接用 apifox 、yapi 等工具自行导入，swagger 有提供 json 链接的，设置自动同步，不知道多香，apifox 还有 ts 类型生成

[securityCoding]

自己去看 pb

[wkong]

我们都是手撸 swagger

https://github.com/TangSengDaoDao/TangSengDaoDaoServer/tree/main/assets/swagger

我们开源的商用级别的即时通讯软件

[tsanie]

redoc demo: https://redocly.github.io/redoc/
Docker Engine API: https://docs.docker.com/engine/api/v1.43/

[konakona]

swagger 的 yaml 可以导入 apifox 、postman 。

[brader]

swagger 也是文档，你可以说它丑，但是说没给文档就过分了，颠倒黑白

[uni]

普通的系统全员全栈才是正解，沟通成本太高了

[jorneyr]

我认为 swagger 的丑不只是说界面丑，而是很多地方不够好用，并且污染 controller ，例如不能很好的处理响应有成功、失败，成功情况 1 的响应结构，成功情况 2 的响应结构 (很多人的接口就这么干)，对结构里特殊字段的描述，响应示例等。

[oppoic]

楼主的图，你这是 swagger ？


花里胡哨随着时间推移都废弃了，还是 swagger 这种能实时读取的能持久下去。看不懂让后端好好学学，swagger 非常灵活

最后，V 站传图的正确姿势： https://www.v2ex.com/t/846267

[unt]

@uni #39 对，是的，我现在很多接口自己写了，沟通成本太高了。自己写要快得多

[theyzw]

swagger 的 ui 不好看是真的，换个皮用 knife4j

[keppelfei]

你应该问，后端不写注释或者更靠谱，openai 有的是靠注释、注解来生成 swagger 的

[gynantim]

自己看代码，自己改后端

[wizzer]

swagger 的界面可以自己改改嘛，比如我改的：

https://demo.budwk.com/api/openapi/#/load/openapi.json

[TingFengShuo]

都给你写 swagger 了知足吧

[nerkeler]

我还以为没给接口文档呢，文档描述不清楚可以找后端描述清楚，文档不好看？基础的样式就是最好的选择，花里胡哨的，你喜欢万一其他人嫌弃呢？还狗都不看。我遇到的前端都是想把问题抛给后端，一个入参格式转换都不想做。

[unt]

@TingFengShuo #47 文档属于公司资产啊，我为公司考虑，我自己手里是有适合自己的文档（ insomnia ）的

[StateMa]

看见没 头顶就有个魔幻生物哎，op 说了后端文档不清晰，接口调试时间成本高，到你嘴里就成菜了？

我感觉能力不是主要问题，傲慢才是。

合着把自己的本职工作甩出去包装成能力不足就是本事强啊？张口一个抛开事实不谈味太冲了，下次发表前记着看看回复框右下角的字。


@aogg ？

[cooper]

我们之前是前端定义接口。 先定义，mock ，最后对接。

[me1onsoda]

@StateMa 你才是魔幻生物吧？ op 是正文还是标题体现了你说的“op 说了后端文档不清晰，接口调试时间成本高”？自己刚开始说的嫌弃丑陋，说着说着又变成文档不清晰。op 自己这表达能力嫌弃别人文档不清晰也是挺乐的

[version]

swagger 如果服务端注释生成的..那可读性是很差的.基本和没文档差不多..
提供的模型定义基本没啥用.crud 的接口可能服务端自己都没测试过..

还有就是 业务需求..后端自己都不提供模拟数据参数.只顾说文档和接口已经提供.自己摸索
当前端辛苦查看文档.模拟出数据插入的时候..发现报错了..问后端..后端答复是查看下日志..是 bug.改了.等几分钟部署再试试.

目前大部分现状就是这样...别问我怎么知道的.我遇到的很多 java 老都这样..所以我害怕和 java 对接.

最后我不是前端..我是后端..我不想成为上面说的那种人.都会提供字段文档+postman+业务页面案例假数据

[fantathat]

替后端说两句，swagger 本身没问题，问题是后端没有按照 restful 和 swagger 规范来，就是一个大 json ，出了问题找不到人，没有人来配合前端。我去，怎么感觉是在替 swagger 说了两句

[zqguo]

这个要向上反馈，像我们后端在 ERD 评审完成之后就需要进行接口设计，设计好之后和前端做接口评审，接口编写有一个专门编写的平台，这个流程要集成到项目流程规范，有流程、规范这个事就好执行了。

[zqguo]

评论区戾气太重，互相攻击意义在哪里，把问题暴露出来，想办法怎么解决，更好的协同不都是为了大家工作舒服些，减少点沟通成本？

[barbery]

我们用的是 graphql ，可以自动生成文档，字段类型和注释都有说明

[LeonardSc]

向上反馈

[buffzty]

我是直接共享一个 postman 账号出去,所有人都在里面看,postman 请求数据可以注释 比文档方便多了

[StateMa]

@me1onsoda 合着后面的补充不是 op 是吧，那后面 op 说的选择性无视？

[tudou527]

当时做 oneapi.app 的一个原因就不想被这种事情卡住。只要后端的代码他们自己能看懂前端就能用

[chf007]

swagger 就够了呀，只是美丑的问题，又不是没有接口文档

[lovelylain]

proto 即文档，字段与功能一致，标清楚字段含义哪些必填哪些选填。想要单独的文档我是反对的，文档与接口定义分离的后果往往就是文档不及时更新，然后 OP 又要发帖，后端不及时更新 api 文档怎么办。

[zhang77555]

不用解决，有锅直接甩

[huajia2005]

swagger 这种感觉侵入性太强了,目前用的是 smrt-doc,通过注释生成 html 或者 swagger 以及 postman,都是 java doc 注释,没啥侵入性
https://github.com/smart-doc-group/smart-doc

[miaotaizi]

@unt 为公司考虑, 你是要笑死我, 然后公司把你开了

[skiy]

rap2.taobao.org BUG 虽然多了点，但勉强能用。数据要动态扩展的另说。

[wanniwa]

可以让后端接一下这个 https://doc.xiaominfo.com/ ，swagger 的一个新的 ui

[th00000]

"Swagger 狗都不看"，你再骂！

[xausky]

虽然不说精通，前端也稍微懂点后端吧，后端也稍微懂点前端吧，像我们这边接口文档一般用 swagger 的 json 导入到 apifox 给前端，有时候前端着急都直接去看看 Controller 就完了，有时候后端接口有小的改动也可以前端代码里面一搜索一起改了就好了，人人都只管自己端的东西，然后要求对方给完美的交付物的话那中间连接这块就是事多。

[1044523901]

"Swagger 狗都不看"，再骂！

[aino]

直接后端代码丢给前端去对接，代码就是最好的接口文档😆

[xiaoHuaJia]

swagger 文档都给了，稍微在问一下沟通一下，互相包含以下的事情，还在这里抱怨，那只能后端都学一下前端，直接挤掉前端岗位，前端学后端直接挤掉后端岗位，无沟通成本。开卷

[daimubai]

连个 swagger 都看不明白吗。。。

[sampeng]

@unt 那不是 swagger 的问题。。是人的问题。找后端 leader 说，这样不行。要改。我见过很多后端图省事把数据库直接反回来，前端自己挑自己用的。。然后零注释

[xiaowei7777]

swagger 都没得你见过吗？

[yrzs]

作为后端 我直接生成 ts 包，连所有的 interface 每个字段都有注释，直接调用就完事。

[Rehtt]

生成 swagger 拖到 yapi 就好了

[PendingOni]

记得之前项目接口文档都是在 ApiFox 上谁开发的接口谁写文档 与其和 swagger 这种工具死磕不如换一种管理思路

[tairan2006]

我不爱用 swagger ，而且我一般是先写文档后开发的。不然让前端等接口？

[CQdake]

这个请求参数我感觉挺清晰的啊，有啥不明白？可能是这个接口比较简单？

[Jinnn]

有 swagger 了就好办，我在前端项目定期抓 swagger 生成的配置文件，把接口入参和返回转换为 ts 类型定义，写项目很舒服了

[hansomeneil]

@owen800q #1 真要是忙到不写文档，或者压根没有写文档的硬要求，那他给你元数据让你自己生成 api 文档，那也不敢用啊。。。太不稳定了，他改你也得改

[hansomeneil]

@owen800q #1 这问题太大了，肯定要说道说道的

[unt]

@buffzty #59 这也是个办法，这个就叫做“协同”，只不过是共享的一个账号而已

[lxy]

editor.swagger.io 各种注释 swagger 示例都可以做到，只是后端不愿意写罢了，我估计他只加了注解，其它什么也没写。

[happy321]

我们前端也会自己写接口，就是他也不提供文档了

[iseki]

swagger 是个工具，文档规范新的现在叫 OpenAPI ，一般说 swagger 文档都是这个，工具你可以自己选

[EvaCcino]

前后端直接改用 Protobuf

[vHypnos]

有 swagger 的话，我觉得不能说没有文档，还有比 swagger 更好用的吗

[xudaxian520bsz]

额，RunnerGo 才是解决方案

[ghost024]

我们组是如果不写接口文档的话，前端直接就开操了，所以所有人对接的时候，先出文档，再说对接的事情，而且请求参数和返回参数分有必须参数和非必须参数两种，反正开发之前，先写文档都得一天多。。。。。（然后如果接口改了，还得同步去改文档）

[afutureus]

用的 Apifox ...

[AmaQuinton]

1. 如果给外部调用，给其他公司使用，都会写接口文档，加测试示例
2. 如果公司同事提供，那就先 postman 调试没有问题，导出后发出，有问题再沟通就行

[dif]

swagger 有个好处是会实时更新，word/markdown 文档需要依赖人工更新得，闲的时候还行，改一个接口同步一下文档，忙的时候就顾不上了，久而久之，文档与代码基本上落下好几个版本。
没有完美的解决方案，前后端多沟通吧

[leichnX]

转行做全栈，自己负责的功能，前后端都自己上，不扯皮，接口爱咋定义就怎么来，爱咋写咋写（前提是能过代码审查）

[mcluyu]

笑死了，评论区一堆连接口文档都写不明白甚至不写懒得写的还好意思出来现眼。。。屎山不就是这样堆出来的，注释没有，文档没有。。。 说人代码屎山的和自己疯狂堆屎的往往是一批人

[wangritian]

swagger 不是用来看的，是用来自动生成 sdk 的
对接过 go java python react ，他们的 sdk 都是我写工具生成的
接口函数，输入输出对象，和所有的注释全都有

[sdjl]

后端不写文档的原因只有一个：“我凭啥给你？”

[iosyyy]

你让后端用 apifox 做测试 自动就会有个文档了