后端不写 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 。而且一股脑的把所有的字段都给你了，还有许多字段是在某一个字段为特定值的时候才会有。这些后端统统不说。