Steafan_ ·Swagger-UI 自定義界面
1. 前言
本節會為大家介紹如何自定義 Swagger-UI 生成界面。
一般來說，Swagger 為我們自動生成的界面就足以滿足我們絕大多數的需求，然而避免不了需要根據業務需求定制 Swagger-UI 界面的情況，盡管這種情況很少。
本節作為 Swagger 三劍客之一 Swagger-UI 的組成部分，將會為大家介紹 Swagger-UI 主流的自定義實現方案，由于本套課程適合于初學者，所以很復雜的實現方式以及一些實現原理將不予介紹。
重點講解內容：
-
主流自定義 Swagger-UI 界面實現方案對比；
-
基于 Swagger-ui-layer 實現自定義 Swagger-UI 界面。
2. 主流自定義 Swagger-UI 界面實現方案對比
對于自定義 Swagger-UI 界面的實現，目前有兩種方法用得最多：
第一種：重定向 v2/api-docs 的訪問路徑到自己自定義的界面
由于 Swagger-UI 的解析原理是通過訪問 v2/api-docs 路徑下的 html 文件來解析 json 數據，使用這種方法我們首先需要自定義 html 文件，然后將 v2/api-docs 的訪問路徑指向我們自定義的 html 文件所在地址即可。
這種方法實現起來難度較大，并且需要開發人員掌握一定的前端 html 相關知識，還需要開發人員有一臺屬于自己的服務器來部署自定義的 html 文件，對絕大多數開發人員并不推薦使用該方法。
第二種：使用 Swagger-ui-layer 實現自定義 Swagger-UI 界面
出于強烈的 Swagger-UI 界面自定義需求，Swagger 的社區開始活躍了起來，前兩年就可以在 Swagger 社區中看到 Swagger-ui-layer 這一名詞。Swagger-ui-layer 是一款專門針對自定義 Swagger-UI 界面而開發的工具包，其支持 Java 平臺等其他主流平臺集成使用。
使用 Swagger-ui-layer ，我們只需要進行兩步操作，即可完成自定義 Swagger-UI 界面的功能，這種方式集成方便，配置簡單，是業界用得最多的一種方式，也是我推薦使用的一種方式，本文就是使用 Swagger-ui-layer 來介紹如何自定義 Swagger-UI 界面。
下面就讓我們來看一下如何使用 Swagger-ui-layer 來實現自定義 Swagger-UI 界面吧！
3. 基于 Swagger-ui-layer 實現自定義 Swagger-UI 界面
使用 Swagger-ui-layer 來自定義 Swagger-UI 界面需要兩步驟即可完成：
3.1 第一步 集成 Swagger-ui-layer 依賴到項目中
我們都知道，向項目中集成依賴的方式有很多種：我們可以直接把依賴包拷貝到項目中去，也可以通過主流包管理工具將依賴進行統一管理，從而將依賴集成到項目中去，本套課程在開篇時已經說明使用 Maven 包管理工具來構建項目，所以這里關于 Maven 的相關知識不再介紹，有不知道同學可以自己去查一下相關資料。
出于方便考慮，上述依賴截圖對應下面依賴代碼：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>com.github.caspar-chen</groupId>
<artifactId>swagger-ui-layer</artifactId>
<version>1.1.3</version>
</dependency>
代碼解釋：
上方的依賴為 Swagger 的依賴，下放的依賴為 Swagger-ui-layer 的依賴，同學們可以直接將上述兩個依賴直接拷貝到自己項目的 pom 文件中去。
在將依賴拷貝到項目的 pom 文件中去后，等待依賴加載完畢即可。
3.2 第二步 對 Swagger-ui-layer 進行必要的配置
這里我們需要對上一章節中介紹的 Swagger 配置類進行一些必要的修改，修改好的配置類代碼如下：
@Bean
public Docket ProductApi() {
return new Docket(DocumentationType.SWAGGER_2)
.genericModelSubstitutes(DeferredResult.class)
.useDefaultResponseMessages(false)
.forCodeGeneration(false)
.pathMapping("/")
.select()
.build()
.apiInfo(productApiInfo());
}
private ApiInfo productApiInfo() {
ApiInfo apiInfo = new ApiInfo("慕課 Wiki Swagger 課程數據接口文檔",
"慕課 Swagger-Wiki 演示系統",
"1.0.0",
"API TERMS URL",
"聯系人郵箱",
"license",
"license url");
return apiInfo;
}
代碼解釋：
第 2 行，我們通過 DocumentationType.SWAGGER_2 屬性聲明項目中所使用的接口文檔類型是 Swagger 2 版本的，這是必須的。
第 9 行，我們通過向 apiInfo 方法將我們自定義的 Swagger 界面描述信息填充到 Swagger-UI 中去。
第 12 行，在 productApiInfo 方法內部，我們對 Swagger 界面上所展示的信息進行一些必要的描述。
以上就是配置類的最關鍵的三個部分，當我們配置完這些屬性之后，啟動我們的項目即可看到界面效果。
顯示效果：
Tips :
- 注意 Swagger-ui-layer 開源工具的版本和 Swagger 版本的區別，雖然官網上說 Swagger-ui-layer 的版本并不會因為 Swagger 版本的變遷而受到影響，但是這里還是要說一句：如果是 Swagger 2.0 或以上版本，則請使用 Swagger-ui-layer 的最新版本 1.1.3。
- 一般情況下，我們不需要針對 Swagger-UI 界面進行自定義配置，如有特殊要求，例如公司或企業定制時才會用到，然而，使用 Swagger-ui-layer 是最常用的方案。
- 本節只是對 Swagger-ui-layer 進行一個相對簡單的介紹，如果同學們感興趣可以去 Swagger-ui-layer 的 github 上獲取更多相關資料，出于對開源貢獻者的尊敬，這里附上鏈接地址：https://github.com/caspar-chen/swagger-ui-layer 。
4. 小結
本小節針對如何自定義 Swagger-UI 界面做了詳細的介紹，從當前可用的兩個主流方案開始，通過對比當下主流方案的區別，選擇了適合本課程的實現方案，同時針對該實現方案在具體實操環節中容易出現的問題做了必要的提醒，希望同學們在實操的時候可以一次成功。
2025 imooc.com All Rights Reserved |