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

unt · 2023-07-25T15:03:23Z

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

swagger

手码

文档

萤石

108 replies • 2023-10-14 22:42:51 +08:00

1 2

❮

❯

owen800q

Jul 25, 2023 via iPhone

1

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

dumbass

Jul 25, 2023 via iPhone

2

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

owen800q

Jul 25, 2023 via iPhone

3

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

JLX

Jul 25, 2023

4

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

SuperManNoPain

Jul 25, 2023

5

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

LeegoYih

Jul 25, 2023

6

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

Vegetable

Jul 25, 2023

2

7

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

dayeye2006199

Jul 26, 2023 via Android

8

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

zachlhb

Jul 26, 2023 via Android

1

9

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

MozzieW

Jul 26, 2023

10

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

你自己看着办

sjn9588

Jul 26, 2023

11

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

IvanLi127

Jul 26, 2023 via Android

12

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

tsanie

Jul 26, 2023

13

不喜欢 swagger ui 的我推荐个 redoc

Imindzzz

PRO

Jul 26, 2023 via Android

14

https://yapi.pro

qinfengge

Jul 26, 2023

15

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

me1onsoda

Jul 26, 2023

16

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

lihexinkai

Jul 26, 2023

2

17

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

cnbattle

Jul 26, 2023

18

看不到图，

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

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

fumichael

Jul 26, 2023

19

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

EchoAI

Jul 26, 2023

2

20

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

unt

OP

Jul 26, 2023

1

21

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

unt

OP

Jul 26, 2023

22

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

ruoxie

Jul 26, 2023 via iPhone

23

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

HelloWorld556

Jul 26, 2023

24

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

PlsDontStop

Jul 26, 2023 via iPhone

25

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

LavaC

Jul 26, 2023

26

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

Desiree

Jul 26, 2023

27

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

rockddd

Jul 26, 2023

28

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

fumichael

Jul 26, 2023

29

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

InDom

Jul 26, 2023

30

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

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

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

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

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

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

aogg

Jul 26, 2023

31

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

MENGKE

Jul 26, 2023

2

32

评论区后端集体破防

BG7ZAG

Jul 26, 2023

33

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

securityCoding

Jul 26, 2023 via Android

34

自己去看 pb

wkong

Jul 26, 2023

35

我们都是手撸 swagger

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

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

tsanie

Jul 26, 2023

36

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

konakona

Jul 26, 2023

37

swagger 的 yaml 可以导入 apifox 、postman 。

brader

Jul 26, 2023

38

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

uni

Jul 26, 2023

39

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

jorneyr

Jul 26, 2023

40

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

oppoic

Jul 26, 2023

2

41

楼主的图，你这是 swagger ？

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

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

unt

OP

Jul 26, 2023

42

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

theyzw

Jul 26, 2023

43

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

keppelfei

Jul 26, 2023

44

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

Stop

Jul 26, 2023 via iPhone

45

自己看代码，自己改后端

wizzer

Jul 26, 2023

1

46

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

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

TingFengShuo

Jul 26, 2023

47

都给你写 swagger 了知足吧

nerkeler

Jul 26, 2023

48

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

unt

OP

Jul 26, 2023

49

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

StateMa

Jul 26, 2023

50

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

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

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

@aogg ？

cooper

Jul 26, 2023

51

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

me1onsoda

Jul 26, 2023

52

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

version

Jul 26, 2023

4

53

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

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

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

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

fantathat

Jul 26, 2023

54

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

zqguo

Jul 26, 2023

55

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

zqguo

Jul 26, 2023

56

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

barbery

Jul 26, 2023

1

57

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

LeonardSc

Jul 26, 2023

58

向上反馈

buffzty

Jul 26, 2023

59

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

StateMa

Jul 26, 2023

60

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

tudou527

Jul 26, 2023

61

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

chf007

Jul 26, 2023

62

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

lovelylain

Jul 26, 2023 via Android

63

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

zhang77555

Jul 26, 2023

64

不用解决，有锅直接甩

huajia2005

Jul 26, 2023

65

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

miaotaizi

Jul 26, 2023

1

66

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

skiy

Jul 26, 2023

67

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

wanniwa

Jul 26, 2023

68

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

th00000

Jul 26, 2023

69

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

irrigate2554

Jul 26, 2023

70

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