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