description: 基于 swagger2, openapi3 规范的接口文档 UI UI 展示 1.背景 花业余时间开发了这个文档项目，在公司内部也使用一段时间了，但是应该还是会有很多 bug ，欢迎小伙伴们一起建设由于长期使用 swaggerUI 工具，它的轻量风格个人觉得还是不错的，但是它的整体使用体验确实不好，用过的可能都有体会，尤其是阅读接口的 schema 定义，这里就不一一列举了（由于语言表达能力有限，手动🐶保命，毕竟我在说鼻祖，等下会不会被砍😭）开源的 openapi 文档 redoc ，好像没有调用接口进行测试的功能，UI 风格也不太好用，可能看习惯了 swaggerUI 的缘故apifox ，除了强行喷不喜欢它的 UI 风格，请求参数和 model 定义成嵌套表格展示有点难受，好像找不出什么理由了😂，还有就是 apifox 是托管式，swagger.json 更新后，需要重新导入接口，有点麻烦以上种种其实都是废话，不装了，摊牌了😂，国产开源不易，github 求 star 支持一下，欢迎熟悉 swagger 和 openAPI 规范的小伙伴来把这个项目建设好，如果这个项目做好了想去支持 java ，golang 的相关 web 开发框架的适配 2.简单介绍下 openapiUI(对标 swaggerUI) 2.1.openapiUI 是一个简单轻量、比 swagger-ui 更美观的 openapi 接口文档，可以快速的生成模拟请求参数并调用 api 请求，如果接口有改动，只需要刷新链接就可以重新加载接口信息了，也可以连接本地开发服务。比 swagger-UI 多了很多功能，例如：可以全局设置 Token, 避免每个请求都去塞 Token ； UI 阅读体验很好，尤其是看接口定义的 schema ；可以改接口超时时间，方便测试；可以快速 mock 请求参数；可以根据 schema 定义的正则进行校验；手动填写参数的体验比 swaggerUI 提升了不少等等等2.2.openapiUI 的 github 地址是：github.com/rookie-luochao/openapi-ui，求 star ，求一起共同建设，灰常感谢🙏 3.openapiUI 网站域名 CN: www.openapi-ui.comUS: docs.openapi-ui.comUS2: docs.openapi-ui.com 4.项目技术栈 因为项目功能不是特别复杂，也不需要考虑兼容性，所以项目的技术栈非常新颖，追着版本跑的那种，如同有需要你可以学习下项目的技术架构项目主要技术栈为：vite5 + react18 + typescript5 + react-router6 + antd5 + zustand4 + emotion(cssinjs) + docker + docker 容器化部署 + docker 环境变量注入项目工程化配置为：eslint + typescript-eslint + husky + lint-staged + prettier + commitlint如果你做业务开发的话，推荐增加openapi2typescript，可以自动生成 axios 请求和接口的 ts 定义、react-query，可以自动实现自动 loading 和接口联动，具体如何结合使用可以参考我搭建的前端开发脚手架，目前支持 react18 模板、vue3 模板，我们可以一起完善模板的技术栈和 UI Layout 结构 5.目前支持的数据格式 5.1.支持 swagger2 规范，json 或者 yaml ，即：swagger2.json/swagger2.yml5.2.支持 openapi3 规范，json 或者 yaml ，包含 3.0.x 、3.1.x ，即：openapi3.json/openapi3.yml 6.目前支持的 3 种使用方法 6.1.输入 swagger2/openapi3 的网关地址，这种使用方式的前提是 openapi 文档已经做成了 get 接口，这种使用方法可以分享 url ，别人拿到 url 可以回显到你当前正在测试的接口6.2.上传 swagger2/openapi3 文件，由于是上传的文件，数据太大，url 无法携带，后面尝试使用 base64 测试一下6.3.输入 swagger2/openapi3 文本，同 2 7.快速生成模拟接口请求参数 其实整个文档比较关键的一部分就是 mock 请求参数的合理性，暂时只是比较粗略的一个 mock ，后续会重点对 mock 策略进行升级如果 openapi 接口请求参数 schema 定义了 format 字段，则使用openapi-sampler 去生成模拟请求参数，具体的规则可以点击 url 跳转查看，它也只是简单的一个 mock如果 openapi 接口请求参数 schema 没有定义 format 字段，则使用 faker 去生成模拟请求参数，预定义了一些参数名称规则，如果请求参数的名称正好命中这些预定义的参数名称，则按照命中规则进行 mock 数据，如果参数名称没有命中预定义的规则，则根据参数类型简单进行 mock 8.手动填写 body 复杂数据结构 引入 monaco-editor 编辑器，填写任何字段都会有类型提示，增加填写数据的友好性 9.支持多语言、提供一个国际化接入模板 9.1.支持中文9.2.支持英语 10.为方便开发，支持一些全局配置 10.1.支持配置接口请求超时时间，默认的接口超时时间是 2 分钟，为了测试接口的灵活性，如果有些接口需要快速响应，等待 2 分钟那简直要命，所以将接口超时时间做成可配置，方便调试10.2.支持配置接口请求 Authorization ，因为大部分的接口都需要 Authorization ，如果切换接口都需要重新填写 Authorization 的话，显然很不安逸。程序员个体大部分都是讨厌手动重复的团队，所以怕麻烦的可以全局配置一下 Authorization ，这样每个接口都不用填写了。如果有些接口的 Authorization 和全局的 Authorization 不一致也不要紧，你在当前接口重新填写一下，会覆盖全局的 Authorization ，这样就避免了被全局 Authorization 干扰。或者特殊接口你就重新取个 header key ，例如：x-code ，这样页面的参数都不会显示 Authorization ，更加不会冲突了 11.如果不能连接内网 api 如果不能连接内网 api 的情况, en...好像也没什么好办法，你可以在本地运行此项目或者使用 docker 在本地或者服务器部署此项目，这样你就可以愉快的访问内网 api 了 12.如果你想分享某个接口的 url 给别人快速定位 为了保持 url 的简洁性, 如果想要分享 url 供他人快速访问，则需要点击页面右上角的 分享 url 按钮 生成分享链接，然后再进行分享。其实是可以直接把 api 地址啥的挂在 query 上的，那样分享起来更方便，但是个人喜欢简洁点的 url(轻微强迫症患者)，后续讨论一下怎么挂参数吧 13.如果你想同时查看多个 api 网关 由于本项目就是个纯粹的前端静态页面，并没有接入后端进行状态管理，API 存储管理等功能，所以暂时就不具备存档的能力。该 openapiUI 项目默认的缓存策略是 session storage, 可以同时打开多个页面去查看多个 api 网关 14.未来的展望 需要小伙伴一起来建设由于使用量不大，bug 还很多，需要不断修复 bug精细化的支持 openapi3.0.x 和 3.1.x ，做到都能正常展示优化 mock 策略，更好的模拟请求参数支持 postman 这种手动编写请求的功能，这样更方便测试接口支持一套暗黑主题考虑增加：点击 schema 生成 typescript 的 interface 功能，并可以复制 interface ，方便对 ts 的支持 接口, 请求, API, swagger2
