一、Swagger UI移动端的常见应用与问题
1.1 什么场景会用到Swagger UI
很多后端小伙伴写完接口后，都会用Swagger UI自动生成接口文档，省得自己写文档还容易出错。比如做内部项目，测试同学需要查接口的参数、返回值，开发人员在线调试接口，这些场景下Swagger UI特别方便，不过默认的Swagger UI是为PC端设计的，遇到移动端就容易出问题。
1.2 移动端显示的具体痛点
最常见的问题有几个：第一，按钮太小，比如“展开”“发送请求”这些按钮，在手机上和电脑上一样大，手指粗的话根本点不准；第二，内容太挤，接口路径、参数挤在一行，小屏上根本看不清；第三，字体太小，默认的字体在电脑上刚好，手机上就显得模糊；第四，需要横向滚动，比如输入参数框太窄，要左右划才能看完，特别麻烦。
二、适配优化的核心思路
要解决这些问题，核心就是围绕“小屏操作”来调整，不用改Swagger的源码，只用给它加一层自定义的样式规则就行，就像给衣服加个小补丁，不用重新做衣服。具体的思路有四个：
2.1 让容器占满手机屏幕
去掉左右的留白，这样能充分利用手机的空间，不会有黑边，看起来更清爽。
2.2 放大可点击元素
比如按钮、输入框，放大到手指能轻松点击的尺寸，避免误触。
2.3 调整字体大小
把字体放大到16px左右，适合手机阅读，不会费眼睛。
2.4 优化接口列表的布局
小屏上把接口的方法（GET/POST）和路径竖排，避免挤在一起，比如原来的一行“GET /api/user/list”，改成“GET”在上，“/api/user/list”在下，这样就不会拥挤。
三、详细适配的代码示例（技术栈：CSS）
这里我们用的是CSS，也就是网页的样式代码，只需要把这段代码添加到Swagger的自定义样式里，就能自动适配移动端，不用改Swagger的任何源码。代码里每一行都加了注释，方便理解：
/* 技术栈：CSS，用于自定义Swagger UI的移动端样式，无需修改Swagger原生代码 */
/* 当屏幕宽度小于768px时（这是大部分手机的屏幕宽度，可根据需求调整），应用以下样式 */
@media screen and (max-width: 768px) {
/* 1. 调整主容器：去掉左右留白，加内边距避免内容贴边，确保不超出屏幕 */
.swagger-ui {
width: 100% !important; /* !important仅用于覆盖Swagger自带样式，非必要不常用 */
margin: 0 !important; /* 清除默认外边距，让容器占满屏幕 */
padding: 0 8px !important; /* 左右加8px内边距，符合手机阅读手感 */
box-sizing: border-box !important; /* 内边距不会让容器超出屏幕宽度，避免横向滚动 */
}
/* 2. 放大按钮：适配触摸区域，避免误触，占满容器更整齐 */
.swagger-ui .btn {
font-size: 16px !important; /* 字体放大到手机易读尺寸 */
padding: 10px 16px !important; /* 增大按钮点击区域 */
min-height: 48px !important; /* 符合移动端触摸区域的行业标准，最小尺寸48px */
width: 100% !important; /* 按钮占满容器，无多余空白 */
margin: 8px 0 !important; /* 按钮之间加间距，避免拥挤 */
}
/* 3. 优化接口项布局：小屏竖排显示，避免方法和路径挤在一起 */
.swagger-ui .opblock-summary {
font-size: 15px !important; /* 接口名字体放大，清晰易读 */
padding: 12px !important; /* 增大点击区域，方便展开收起 */
flex-direction: column !important; /* 方法和路径从横排改成竖排 */
align-items: flex-start !important; /* 左对齐，符合阅读习惯 */
gap: 4px !important; /* 方法和路径之间加间距，不会挨在一起 */
}
/* 4. 适配输入框和下拉框：占满容器，方便输入，避免横向滚动 */
.swagger-ui input,
.swagger-ui textarea,
.swagger-ui select {
width: 100% !important; /* 占满容器，无需横向滚动 */
font-size: 16px !important; /* 输入字体适配手机，清晰可见 */
padding: 8px !important; /* 增大输入区域，方便手指点击 */
box-sizing: border-box !important; /* 内边距不超出容器 */
margin: 4px 0 !important; /* 输入元素之间加间距 */
min-height: 40px !important; /* 最小高度，符合触摸标准 */
}
/* 5. 调整接口返回内容：自动换行，避免横向滚动 */
.swagger-ui .response-content {
white-space: pre-wrap !important; /* 长内容自动换行，适配小屏 */
word-break: break-all !important; /* 长单词自动拆分，避免溢出 */
font-size: 14px !important; /* 适配小屏的字体，不会太挤 */
}
}
四、适配方案的优缺点和注意事项
4.1 优缺点分析
这个方法的优点很明显：第一，不用改Swagger的源码，Swagger升级后也能继续用，只要类名不变就有效；第二，操作简单，把CSS代码添加进去，几分钟就能完成适配；第三，灵活可调，可根据自己的需求调整数值，比如把768px改成600px适配更小的屏幕，或者把按钮高度改成50px更顺手。
当然也有缺点：第一，如果Swagger官方后来改动了类名，比如把原来的.swagger-ui改成.swagger-container，那原来的选择器就会失效，需要同步更新代码；第二，用!important虽然快，但如果不注意，多个样式重叠时可能会出现意外效果，所以尽量只在必要的时候使用，还要定期检查样式是否生效。
4.2 适配时的注意事项
首先，触摸区域的大小要严格遵守，移动端可点击元素（按钮、输入框）最小要48px×48px，这是行业通用的标准，像微信、淘宝这些APP的按钮都是这个尺寸，不然手指粗一点就点不中，体验很差。其次，字体大小尽量用16px以上，手机屏幕小，14px以下的字体看久了会累，基础字体设成16px比较合适。然后，一定要避免横向滚动，小屏上横向滚动特别麻烦，所以所有元素都要设成占满容器，还要用box-sizing:border-box来控制尺寸，避免超出。另外，写CSS的时候，类名要从浏览器开发者工具里看，打开Swagger页面按F12，选中要修改的元素，在Elements面板里查看它的class属性，把选择器写对，不然样式不会生效。还有，不要随便改Swagger的核心结构，比如隐藏元素，可能会导致接口调试失败，只改样式就好，别碰代码逻辑。
五、总结
Swagger UI的移动端适配，其实没有想象中复杂，核心就是围绕“手机操作”调整样式，不用改复杂的代码，只要用CSS做一套小屏专属的规则就行。这个方法适合大部分开发者，尤其是后端小伙伴，不需要懂太多前端知识，只要把这段适配的CSS添加到Swagger的自定义配置里，就能解决大部分移动端的显示问题。当然，以后如果Swagger升级了，记得检查类名有没有变化，确保适配还能生效。另外，你还可以根据自己的需求调整数值，比如把按钮的大小再改大一点，或者字体再放大一点，适配不同的手机屏幕，让接口文档在移动端的使用体验大大提升。
Comments