Swagger UI 布局定制实战：5 分钟重排你的 API 文档页

Swagger UI 布局定制实战5 分钟重排你的 API 文档页【免费下载链接】swagger-uiSwagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-uiSwagger UI 的默认界面结构比较固定顶部是 API 信息中间是接口列表底部是数据模型。如果你的产品有自己的品牌文档页这个骨架往往不合身。布局机制就是 Swagger UI 给出的官方答案把你的根组件注册成插件再把名字传给layout参数文档页的模块顺序、列数、哪些区块出现都归你管。成本并不高——你要写的是一个 React 组件内部调用 Swagger UI 提供的区块拼装页面即可。官方文档里就有一份现成示例docs/customization/custom-layout.md。布局和布局插件是两回事先分清 讲 Swagger UI 布局定制的文章里这两个概念经常被混为一谈但它们其实是分工合作的两部分。布局是一个 React 组件是整页的根。默认的 BaseLayoutsrc/core/components/layouts/base.jsx按这个顺序拼装信息区 → 服务端与授权区 → 过滤框 → 接口列表 → 模型列表。看它的源码会发现每个区块都是用getComponent(operations)、getComponent(InfoContainer)之类的调用取出来的你可以把它理解成一份装配清单。布局插件则不画页面它管状态某个区块显不显示、处于什么模式、过滤词是什么。说白了布局组件定页面的骨架布局插件管骨架上的开关。布局插件真正干的活一套显隐状态机src/core/plugins/layout/actions.js 里的动作一共四个updateLayout、updateFilter、show、changeMode。其中最有用的是show(thing, shown)——它给指定名字记一个是否显示的开关isShown(thing)再把它读回来。内置的另一个布局 XPane就是用它控制编辑器栏的显隐const showEditor layoutSelectors.isShown(editor) layoutActions.show(editor, !showEditor)Swagger UI 里的编辑器、过滤框都是靠这套机制切换的。你自己写布局时也能复用它给想受程序控制的区块起个名字显隐逻辑交给选择器处理。状态实现集中在 src/core/plugins/layout/。自定义布局的两种用法整体替换 vs 包一层扩展 整体替换自己写根组件只渲染想要的区块。比如只做一个纯接口列表页const Operations getComponent(operations, true) return div classNameswagger-ui{Operations}/div包一层扩展不想重造轮子时直接把默认布局取出来在外面套自己的内容const BaseLayout getComponent(BaseLayout, true) return divMyHeader /BaseLayout //div不管选哪种最后一步都一样——注册组件并启用SwaggerUI({ url: /openapi.json, plugins: [MyLayoutPlugin], layout: MyLayout })注意layout传的是组件的名字字符串不是组件本身。忘了在插件的components里登记你的布局不会生效。容易踩的四个坑 ⚠️这几个是最常见的挨个说。漏掉swagger-ui类名。自定义布局的根 div 要带上swagger-ui类名否则全局样式不生效页面直接变回裸 HTML 的样子。误以为layout能直接传组件。它只接受插件里注册过的组件名传组件对象是不行的。以为加载和报错会自动显示。默认布局里有规范没加载完就显示加载动画、加载失败就显示错误信息的逻辑自定义布局需要自己补不然用户在加载时会盯着空白。改主题去动布局组件。换配色、调字号、切深色模式都该去 src/style/ 下改 SCSS变量在_variables.scss深色样式在_dark-mode.scss。布局组件只改骨架皮肤是另一层的事。怎么选按目标对号入座 目标不同投入差别很大。可以对照着挑加 logo、加顶部导航用扩展方式包住 BaseLayout 套一层自己的内容内部结构不用动。页面结构要彻底变双栏、只显示接口、加侧边 Tab整体替换方式自己写栅格用getComponent取需要的区块。只想隐藏某个默认区块比如 Models先试show机制不必为此新写一个布局。只改视觉风格直接改 SCSS 变量和深色模式样式布局一行都不用碰。收尾布局机制的价值在于把骨架、开关、皮肤拆成了三层布局组件定骨架布局插件管显隐状态SCSS 变量管皮肤。会写 React 组件的话你的 API 文档页就可以长成想要的样子了。【免费下载链接】swagger-uiSwagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.项目地址: https://gitcode.com/GitHub_Trending/sw/swagger-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考