共计 3088 个字符，预计需要花费 8 分钟才能阅读完成。
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.com
- US: docs.openapi-ui.com
- US2: 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.yml
- 5.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 的支持
正文完
