Swagger-UI的修改指南

前言

由于打比赛的项目需求，需要使用到Swagger，并且需要稍微改动一下现有的Swagger-UI以符合项目的整体风格，我度娘搜了一下，有从源代码层面讲怎么修改的不多，很多是会贴一个基于BootStrap修改的pom坐标。本文先简单介绍一下Swagger是什么，重点介绍如何对现有的Swagger-UI进行修改。

本文基于Swagger 2.9.2

Swagger Overview

Swagger可以说是现代Web后台开发中的利器，可以使用简单的注解生成项目的API文档，并且拥有接口调试功能，很方便。Swagger的注解说明网上有非常多了，这里我贴一个我觉得讲得不错的：swagger2 注解说明

Swagger-UI的修改

这里先说明一下，我的需求比较简单，只需要把原有UI的顶部工具栏换掉就可以了。这个需求不一定会覆盖到所有人。而且我也是一个前端小白，摸着石头过河，在这里主要以改顶部工具栏为例子，分享一下改源码的思路。

源码的获取

直接去Swagger-UI的Github上clone即可，项目比较大，耐心等待哦~

搭建开发环境

官方的README中有一个比较简明的指南，这里就略过。Setting up a dev environment

观察&修改思路

观察

开发环境搭建完成之后，首先要做的是观察默认的页面，确定要修改那些地方。

项目启动后，正常情况应该看到如下界面

找到自己需要修改的元素，例如我是顶部工具栏，就可以在顶部工具栏，右键–>检查元素，可以发现顶部工具栏是一个样式为topbar的div控制的：

根据官方的开发指南，可以知道这个页面是由dev-helpers/index.html控制的，找到该文件后，可以发现该文件里并没有topbar，说明这一段代码肯定是由某一个js写入的。

使用编辑器的全局搜索功能，搜索关键词topbar，可以发现会搜出很多，我们的重点是要修改顶部标题栏的HTML代码，可以发现，这些HTML代码是在一个名为topbar.jsx的文件里定义的。

顶部工具栏HTML代码

topbar.jsx代码

可以发现它们是一致的，修改这一部分就可以达到我们的目的了。经过目录树的定位，发现topbar实际是一个Swagger-UI的插件。

修改思路

分析到现在，思路已经很明确了：

• 修改topbar.jsx文件（我的需求只要把上图return的内容替换掉就可以了）
• 开发时，将自定义样式链接放在，dev-helpers/index.html中，要部署时，将自定义样式链接放在dist/index.html中

重新编译

使用 npm run build进行编译，结果会输出在根目录下的dist目录，如果怕乱了可以把原来的目录重命名一下，然后把原来dist目录中的index.html拷贝过来，加上自定义样式，就可以预览效果了

思路总结

• 确定自己要修改哪一步份的HTML元素
• 利用全局搜索功能查找关键词
• 修改相关文件
• 重新编译，部署

我觉得最重要的是要善于使用IDE的全局搜索功能