swagger-ui, redoc 好像都快弃坑了， rapi 作者似乎却干劲十足， openapi-ui 作者躺平式更新，大家现在都在用什么 api 文档软件，经济下行，开源弃坑的好像越来越多？
rookie2luochao rookie-luochao 2024-10-12 10:00:30 +08:00 9118 次点击这是一个创建于 415 天前的主题，其中的信息可能已经有所发展或是发生改变。
这里主要是说一些开源免费的 openapi 规范 UI 文档, 那些一上来就无脑各种喷的还请嘴上留情，好歹也算为爱发电，大家都不容易，找点杂事干着也是挺好的
不得不说 apifox 确实是个好东西，目前来看也没咋收费，可是它好像只对 java kotlin 友好，而且我总感觉它好卡，它很多强大的功能我都没有使用过，关键是它为啥必须手动导出 openapi.json 啊，这让想直接根据配置生成 ts http 客户端的前端小伙伴非常蛋疼
目前来看这 4 个包的更新情况：
swagger-ui：功能完善，没咋更新了，就是 UI 体验很差
redoc: 没咋更新了，它竟然不支持测试接口，有点费解
rapi: 作者重新回归，更新活跃，总感觉它的代码阅读起来费劲，不知道是不是我太菜了
openapi-ui: UI 使用良好，使用的最新技术栈构建，代码可读性可维护性高，作者一直在躺平式更新，因为用户太少，没人提 bug
 | 1 xFrye 2024-10-12 10:07:33 +08:00 跟经济下行无关，行情好的时候也有不少这样的弃坑项目。多半是作者心思已经不在这项目上了吧 |
 | 2 rookie2luochao OP @xFrye 可是并没有新的接口规范出来，我看作者们 github 好像都没啥更新动态了 |
 | 3 raphaelsoul 2024-10-12 10:10:12 +08:00 swagger 看上去很美好 但是已经复杂到我不想用的程度了 各类语言框架的支持也不完善 |
 | 4 concernedz 2024-10-12 10:10:15 +08:00 还在用着 yapi ，蛮多 bug 的，但找不到替代品 |
 | 5 nxforce 2024-10-12 10:11:57 +08:00 用 springdoc 吧，虽然仅仅套个 swagger-ui ，但内部实现还是紧跟 springboot 的节奏的。 |
| 6 rookie2luochao OP @joyhub2140 我们 java 类项目用的 apifox+apifox idea ，对代码侵入还好，后端接受性还不错，不用写很多注解 |
 | 7 dingyaguang117 2024-10-12 10:18:53 +08:00 |
| 8 rookie2luochao OP @concernedz yapi 不是很早就弃坑了吗，用这个的目前不多了 |
| 9 rookie2luochao OP @dingyaguang117 这个看着不像接口文档类解决方案啊 |
| 10 rookie2luochao OP @raphaelsoul 各类语言框架的支持，swagger 官方并没有做啊，都是社区做的 |
 | 11 sss15 2024-10-12 10:27:38 +08:00 现在用 apifox ，目前使用体感还好，没有用到付费的服务 |
| 12 rookie2luochao OP @sss15 后端是 java 的话，用这个玩意确实不错，免费的够用了，但是有一点也还没有找到解决办法，就是 apifox 自动同步 openapi.json |
 | 13 securityCoding 2024-10-12 10:35:40 +08:00 最好的 api 文档莫过于 protobuf |
 | 14 lizhien 2024-10-12 10:40:50 +08:00 Scalar |
| 15 rookie2luochao OP @lizhien 这玩意是往付费运营的 |
 | 16 wu67 2024-10-12 11:25:59 +08:00  2 个人觉得, 最好的 api 是特么的把后端的项目 git 权限给劳资打开, 现代后端项目全特么有 mvc 分层了, 详细业务逻辑我看不懂而已, 控制器定义逻辑和参数表我看得懂呀... |
| 17 rookie2luochao OP 1 @wu67 后端说：谁特么跟我把数据库权限，sql 权限放开，老子改个表都不行吗？老子改个数据还得写 sql ，还得负责人审批，老子 xxxxxxx00000000 |
| 18 rookie2luochao OP @securityCoding 这是什么高级玩意，容我看看 |
 | 19 SouthRiverMatt 2024-10-12 11:39:48 +08:00 knife4j 很好用 |
| 20 rookie2luochao OP @SouthRiverMatt knife4j 应该赶不上 apifox, javaer 说用这个玩意还不错，比 swagger/openapi 舒服，它自动解析代码的，精确的信息也需要像 swagger/openapi 一样加注解 |
 | 21 cccxu 2024-10-12 14:28:24 +08:00 scalar ui |
| 22 rookie2luochao OP @cccxu 这东西确实做的挺好，但是和 apifox 一样感觉不够简洁，而且他的目标是付费用户 |
| 23 rookie2luochao OP @cccxu 他们团队这么多人做这个 scalar 文档，经费遭得住吗，收费的文档平台其实应该挺难做的吧，完全不要 api 文档的也很多，而且还有 postman 这些巨头 |
 | 24 burymme11 2024-10-12 14:43:03 +08:00 ApiFox ，有网页版，有客户端，有 IDEA 插件。全公司后端项目都在用，没啥毛病。 |
| 25 rookie2luochao OP @burymme11 我们公司也有部分项目在用，确实是不错的，关键是确实不收费，但是除开 java idea 插件，其他语言好像并不支持 idea 插件 |
 | 26 stiangao 2024-10-12 14:59:40 +08:00 # **[postcat]( https://github.com/Postcatlab/postcat)** 5.2k # [bruno]( https://github.com/usebruno/bruno) 24.4k # **[insomnia]( https://github.com/Kong/insomnia)** 34.2k # **[hoppscotch]( https://github.com/hoppscotch/hoppscotch)** (postwomen) 63.4k # [19 个 postman 替代品]( https://apidog.com/blog/top-postman-alternative-open-source/) |
| 27 rookie2luochao OP @stiangao 你不发不知道，原来文档类软件这么卷，简直是红海 |
| 28 stiangao 2024-10-12 15:02:19 +08:00 postcat https://github.com/Postcatlab/postcat 5.2k bruno https://github.com/usebruno/bruno 24.4k insomnia https://github.com/Kong/insomnia 34.6k hoppscotch(postwomen) https://github.com/hoppscotch/hoppscotch 64.3k 19 个 postman 替代品 https://apidog.com/blog/top-postman-alternative-open-source |
| 29 stiangao 2024-10-12 15:03:34 +08:00 @rookie2luochao 本来想找一个 apifox 替代品，找出了好多项目，一个比一个多 |
 | 30 lepig 2024-10-12 15:06:58 +08:00 apifox 确实挺好用，就是太 TM 卡了，16G 内存，开了七八个标签直接占了 1.7G 多。快赶上 ide 了。 |
| 31 rookie2luochao OP @stiangao apifox 不错啊，都用上 apifox 了，为什么要找替代品 |
| 32 rookie2luochao OP @lepig 这玩意我也感觉卡得很，功能太多了，但是很多都用不上，反正操作页面不简洁，而且巨卡 |
 | 33 momo2278 2024-10-12 15:50:48 +08:00 @cccxu #21 试了下很好用，node 和 web 端都是导入 openapi 配置就能直接用，终于能替换掉 swagger-ui 了 |
| 34 rookie2luochao OP @fox2081 试了下什么很好用，swagger-ui 替换一下现代点的 UI ，其实也好用，轻量且不卡 |
| 35 momo2278 2024-10-12 16:55:51 +08:00 @rookie2luochao #34 就是 scalar ui 啊，确实比 swagger-ui 好看多了 |
 | 36 Hanser002 2024-10-12 16:59:22 +08:00 基于 swagger 生成好了类型就不看 swagger-ui 了，确实不好看也不是很好用，调试直接上 apifox 就行 |
 | 37 davin 2024-10-12 17:03:49 +08:00 到最后，还是 postman 解君愁 |
| 38 rookie2luochao OP @fox2081 我看他们有挂收费标准，就没有对比它了，因为它算付费栏目 |
| 39 rookie2luochao OP @davin postman 确实牛逼啊，有很多人烦登录 |
 | 40 fantasy0v0 2024-10-12 17:11:41 +08:00 我现在的做法是先在 apifox 设计好，然后再让前后端根据这个文档实现。 有点不太理解 swagger-ui ，用这个的话，一般是后端把注释和代码都写好了，然后再生成成文档给前端看吗？ |
| 41 rookie2luochao OP @fantasy0v0 对，一般是后端把代码写好了，然后用一个 swagger 规范的工具，解析后端代码，生成一份接口的 openapi.json 配置文件，然后 swagger-ui 就根据这个配置文件生成 api 文档，前端也可以根据这个配置文件生成调用接口的客户端函数，ts 定义等等内容 |
| 42 rookie2luochao OP @fantasy0v0 我写了一个 [openapi-ui]( https://github.com/rookie-luochao/openapi-ui) 用于展示 api 文档 <br> 维护了一个供前端解析 swagger 配置文件生成前端代码的工具 [openapi-ts-request]( https://github.com/openapi-ui/openapi-ts-request) |
 | 43 coolcoffee 2024-10-12 17:22:35 +08:00 看到楼主的推荐，我先试试从 swagger-ui 换成 rapi 去。redoc 之前尝试使用过，开源的版本功能残废以及付费版本的体验也总是怪怪的。 楼上推荐的什么 apifox 、insomnia 、postman 我觉得太重了用不上，写完接口自动生成接口文档并且网页上能调试才是最方便的，能够及时跟着服务端最新版本走。 |
| 44 rookie2luochao OP @Hanser002 swagger-ui 确实 UI 有点不太好用，但是如果后端如果集成一些现代的 swagger-ui 文档估计就好很多 |
| 45 rookie2luochao OP @coolcoffee 有没有一种可能可以试试楼主写的 openapi-ui https://github.com/rookie-luochao/openapi-ui ，你有 bug ，我立即响应 |
 | 46 heganghua 2024-10-12 17:30:12 +08:00 openapi.json 这是一个啥？ 我都是写完接口后直接同步到 foxapi |
| 47 rookie2luochao OP @heganghua swagger-ui 就是根据 openapi.json 渲染的文档，前端可以根据这个 openapi.json 和后端服务同步，省去写 ts, http 客户端，还有智能提示 |
| 48 rookie2luochao OP @heganghua apifox 没有对应的配置可以供前端使用，所以有点蛋疼，很影响使用体验 |
| 49 rookie2luochao OP @coolcoffee 不要 998 ，不要 98 ，楼主写的 openapi-ui 免费送你，哈哈哈 |
| 50 coolcoffee 2024-10-12 17:46:01 +08:00 @rookie2luochao 我重新对比了一下 openapi-ui 和 rapi 。我觉得 openapi-ui 还有一些没能满足我期待的地方 像美观上来说，method 显示那么大有点亮瞎狗眼；另外我这边看接口的字段请求和返回格式很乱，没有 rapi 那样清晰明了。 从功能角度来说，那个侧边栏折叠状态完全没法用就先不用放出来吧；接口组的折叠功能也还缺失会导致接口数量多了很难找。 |
| 51 rookie2luochao OP @coolcoffee 那把 method 调小一点吧，折叠那就砍掉吧，是不是随意了一点 支持很多搜索条件，随便搜一下关键词，应该都能搜到想要的接口 接口返回 UI 展示可能有些人会喜欢，有些人会不喜欢，因为很多功能都是重新设计的 接受意见改进，欢迎 issue 区提供一些改进意见 |
| 52 rookie2luochao OP @coolcoffee 我个人觉得 openapi-ui 整体还是要简洁一点？ |
 | 53 TGhoull 2024-10-12 17:59:07 +08:00 可以试试 Spring Restdocs ( https://spring.io/projects/spring-restdocs)，上手略有门槛，切入点很新颖，优点是接口 mock 测试和接口文档相结合，可以根据接口 mock 测试代码，直接生成接口文档。 |
| 54 rookie2luochao OP @coolcoffee openapi-ui 最大的优势可能就是整体 UI 布局简洁，query 输入对复杂数据类型支持的比较好 返回结构可能更迎合前端，因为接口测试很多时候都是丢给前端测的，前端太需要了解返回数据的层级了，当然最重要作者的使用风格影响了设计 抛开这些，积极接受用户的功能反馈建议 |
 | 55 rookie2luochao OP @TGhoull 这个怎么没听人使用过？ |
 | 56 BiChengfei 2024-10-12 18:57:02 +08:00 swagger ，各种语言都有对 swagger 规范的实现，很多都是嵌入到项目中，实时生成。 接口信息，本来就是一个轻量级，很成熟的东西，功能做完后，本来没必要更新了 |
 | 57 kalman03 2024-10-12 19:00:45 +08:00 apideploy.com 我开发的，欢迎指导。 |
| 58 kalman03 2024-10-12 19:01:41 +08:00 |
 | 59 rexcelia 2024-10-12 19:22:37 +08:00 Apifox 啊，好多公司在用，又免费 |
| 60 rookie2luochao OP @rexcelia apifox 对 java 的支持没得说，对 go, nodejs, python 的基本上没有支持，所以根据代码生成 api 文档的话，apifox 只对 java 友好 |
| 61 rookie2luochao OP @BiChengfei 用了很多年 swagger, 目前来说没有比它流行的接口规范定义了吧，就是 swagger-ui 设计一直没变过，不太好用，阅读和测试都不是很方便 |
| 62 rookie2luochao OP @kalman03 指导谈不上，我这就是个 UI ，你这是个对标 apifox 的接口管理平台，体量都不一致，我闲下来学习下 |
 | 63 maguowei 2024-10-12 21:35:04 +08:00 scalar +1 |
| 64 kalman03 2024-10-12 22:20:38 +08:00 @rookie2luochao 如果你忽略根据代码生成 API 的部分，那么它也就是个 UI 。支持标准的 OpenAPI （ swagger ）格式导入，导入后就是一个好看的 UI 接口文档。目前一直是免费的。 |
 | 65 unidotnet 2024-10-12 23:38:18 +08:00 这种自动化工具是给懒人用的，最主要的还是人工写好文档，看看那些大公司，Facebook ，Salesforce 之类的接口文档，都写的很详细。Postman collection 都是额外的一些 demo 。 |
| 66 rookie2luochao OP @unidotnet 可是中小公司里面没人愿意写文档，让你抓包的都有，临时甩给你个参数的也有 |
| 67 rookie2luochao OP @maguowei scalar 其实和我同一时期推出来的，有点尴尬，其实我在推出的 2 年前就写了这个工具的前身，只不过是给公司提供的一个 api 托管平台 |
| 68 rookie2luochao OP @maguowei scalar 永不收费的话，我也给它投一票 |
| 69 rookie2luochao OP @coolcoffee 大佬，rapidoc 在接多了一点之后，和 swagger-ui 一样可阅读性很差啊，它是接口折叠性质的 |
 | 70 Akagi201 2024-10-13 06:49:25 +08:00 团队在用 apidog (apifox 国际版), 目前遇到问题有导入 openai.json 文件不能正确解析 schema. 其他还好, 也是用了很久, 几乎能满足我一切需求. |
 | 71 jchnxu 2024-10-13 07:55:06 +08:00 @rookie2luochao #66 是的。。小公司哪里有大公司那么多资源 |
 | 72 cheng6563 2024-10-13 09:32:54 +08:00 @raphaelsoul #3 swagger 本身就没做语言框架集成，是要你手写 json 文档的... |
 | 73 zbowen66 2024-10-13 11:21:36 +08:00 刚入行写的，虽然也没更新了，但对比官方 UI 还是有信心的 https://github.com/bowencool/swagger-ui |
| 74 rookie2luochao OP @zbowen66 刚入行就能写这种东西，还是很优秀了，膜拜大佬 |
| 75 rookie2luochao OP @cheng6563 是的，swagger 只是一个规范，根据代码自动生成 json 文档需要对应语言的实现 |
| 76 rookie2luochao OP @jchnxu 小公司能将就用个文档软件就不错了，越要后端少写点就少写点，不然他不愿意干 |
 | 77 rookie2luochao OP @Akagi201 apidog 也是 apifox 出品吗？ apifox 优点很多，但是有 2 点让我也感觉很坑，一就是很容易卡，二就是推文档后想拿到接口的 openapi.json 很沙雕，无法自动同步 |
| 78 zbowen66 2024-10-13 22:25:32 +08:00 @rookie2luochao #74 当时有大佬指导，可惜很快大佬就跑路了 |
 | 79 rockycc 2024-10-14 00:10:51 +08:00 via Android 无脑 yapi 就行。yapi 本身是没有 bug 的，用了 5 年了，好用得不得了，直接替代 postman 进行接口运行和测试。官方 issue 那些都是别人提的需求，不打算实现而已。一个已经做得非常好软件依旧会有人去提 bug ，去提需求，实际体验是完全 okay 的。我的版本是 1.10.2 。 |
| 80 rockycc 2024-10-14 00:24:00 +08:00 via Android api 文档管理用已有的 yapi 方案就行，就算有 bug ，也有先行者会替你去修。https://blog.opendeveloper.cn/yapi/bug |
| 81 rookie2luochao OP @rockycc yapi 国产里面绝对算很牛逼的了，不知道为什么弃坑了？ |
| 82 Akagi201 2024-10-14 10:27:25 +08:00 @rookie2luochao #77 目前看到 apidog 相比国内版, 有免费版的团队最多 4 人限制, 多了要付费. 我目前还没用到导出功能. 主要设计跟测试上. 我是 mac m1max 没遇到卡过. |
| 83 rookie2luochao OP @Akagi201 它们这种都是 api 托管吧，便于工作空间合作收费，不愿意花钱、追求隐私安全性的还是就 swagger |
 | 84 shubuqi 2024-10-14 12:06:00 +08:00 via Android |
 | 85 crackidz 2024-10-14 12:47:21 +08:00 redoc 有付费版本的，弃坑可能性不大。当然，功能肯定不及付费版本就是了 swagger-ui 其实功能挺完善的了，也没什么问题，不过做文档的话多少有点 UI 上有问题，更方便测试 rapi 没用过，看上去挺不错的样子 openapi-ui 只能说不在审美上，尤其是有大的有小的元素还密集... |
| 86 rookie2luochao OP @crackidz 我就是 openapi-ui 作者，我还是前端，我。。。，rapi 也是借鉴了很多 swagger-ui 设计，连最难用的接口折叠展示都保留着的，其实抄它们的设计也可以，可是当时我并不想啊，求 issue 提点改进意见 |
| 87 rookie2luochao OP @shubuqi 已经没啥更新动态了？ |
 | 88 Bingchunmoli 2024-10-14 13:50:14 +08:00 via Android @rookie2luochao 看起来和 swagger 没有区别，还要用服务器不是内嵌 |
| 89 rookie2luochao OP @Bingchunmoli 还要用服务器不是内嵌是什么意思，上面的所有文档都是可以接入到后端服务上面的 |
| 90 Bingchunmoli 2024-10-14 15:13:34 +08:00 via Android @rookie2luochao 官方插件要么推送给 apifox 要么单独自托管。 |