Swagger-UI 生成界面使用詳解

1. 前言

本節(jié)會(huì)為大家介紹 Swagger 生成界面，即 Swagger-UI 界面的基礎(chǔ)使用方法，包括界面基本元素講解、界面接口內(nèi)容講解以及如何使用 Swagger-UI 界面進(jìn)行必要的接口調(diào)試。

關(guān)于如何集成 Swagger 以及如何查看 Swagger-UI 界面請(qǐng)參考上一章節(jié)中的 ‘SpringBoot 集成 Swgger-UI’ 小節(jié)內(nèi)容，本節(jié)不再贅述。

重點(diǎn)講解內(nèi)容：

• Swagger-UI 界面所有基本元素，界面接口基本內(nèi)容；

• 基于 Swagger-UI 界面進(jìn)行必要的接口調(diào)試。

掌握 Swagger-UI 界面的使用方法是使用 Swagger 進(jìn)行接口調(diào)試的基本組成方式，所以請(qǐng)大家重點(diǎn)掌握該部分內(nèi)容。

2. Swagger-UI 界面基本元素介紹

在本部分我將以圖文并茂的方式介紹在 Swagger-UI 界面上的基本元素，這些基本元素在界面的不同區(qū)域，是界面的基本組成元素。

我將按照 Swagger-UI 界面基本元素所處的不同區(qū)域依次介紹每個(gè)基本元素的含義和作用，下面我們都來(lái)看看有哪些基本元素以及他們所發(fā)揮的作用吧！

在配置好 Swagger 之后，我們?cè)跒g覽器地址欄中輸入項(xiàng)目中 Swagger-UI 界面的路徑即可看到如上圖所示的界面，這就是 Swagger-UI 的核心界面，也是我們使用最多的界面，項(xiàng)目中所有的接口都會(huì)在該界面上顯示。

我們從上到下，依次進(jìn)行介紹：

2.1 第一部分 頂部區(qū)域

在頂部欄區(qū)域的最左側(cè)是 Swagger 的 Logo 圖標(biāo)，我們不需要關(guān)心。

在頂部欄區(qū)域的最右側(cè)是一個(gè) Explore 按鈕，該按鈕的作用就是刷新 Swagger-UI 界面，在我們點(diǎn)擊時(shí)就會(huì)刷新，沒(méi)有其他用途。

在 Explore 按鈕的左側(cè)，是 Swagger-UI 加載 html 界面模板的區(qū)域，這是一個(gè)下拉框，可以選擇我們自定義的界面顯示。

2.2 第二部分 中部區(qū)域

在中部區(qū)域可以看到只有最左側(cè)有內(nèi)容，在右側(cè)是沒(méi)有任何內(nèi)容顯示的。

在中部區(qū)域可以看到一行加粗加黑的字體：“immooc-Swagger-UI-Studying”，這里是用來(lái)描述 Swagger-UI 界面所顯示的主要內(nèi)容，一般使用我們的項(xiàng)目名稱來(lái)描述。

在加粗加黑字體的下方是一行黑色的小字體：“Created by Steafan”，這里是用來(lái)描述 Swagger-UI 界面的作者信息，一般是接口維護(hù)人員或者接口開(kāi)發(fā)人員。

2.3 第三部分 底部區(qū)域

在底部最開(kāi)始的地方，我們可以看到 “user:User Controller” 等字樣，這是我們使用 @ApiOperation 注解的 tags 屬性來(lái)為接口描述的分組名稱，當(dāng)我們點(diǎn)擊 user 之后，字體會(huì)加粗顯示，同時(shí)會(huì)列出所有屬于該 user 分組的接口列表，如下圖所示：

而 User Controller 則是我們這些接口所屬的 Java 類的名稱，這里的名稱通過(guò) @Api 注解描述。

在最底部區(qū)域可以看到 “BASE URL” 字樣，這里的 base url 指的是 Swagger-UI 界面的訪問(wèn)路徑，即：http://host:port/imooc/imooc-user-service/swagger-ui.html （這里的路徑是自己配置的），右側(cè)的 API VERSION 代表當(dāng)前接口的版本。

在上述部分，我們介紹了 Swagger-UI 界面的所有基本元素，接下來(lái)我們來(lái)看看我們開(kāi)發(fā)的接口在 Swagger-UI 界面中都有哪些內(nèi)容。

3. 接口基本內(nèi)容介紹

在接口列表中，我們點(diǎn)開(kāi)之前一直使用的用戶登錄接口 (login.do)，會(huì)顯示出接口的所有內(nèi)容信息，由于接口內(nèi)容太長(zhǎng)，所以我們分塊進(jìn)行講解：

3.1 第一部分 Response Class

我們可以看到在圖片的最上方是一個(gè)接口標(biāo)題，其中，POST 代表接口的請(qǐng)求類型，/user/login.do 代表接口的地址以及接口名稱，最右側(cè)的用戶登錄就是我們使用 @ApiOperation 注解的 value 屬性所描述的接口的作用。

Response Class 表示接口的響應(yīng)信息，即我們請(qǐng)求接口時(shí)返回的響應(yīng)內(nèi)容，Status 200 表示該接口是可以正常使用的（接口狀態(tài)的編碼及意義請(qǐng)自行查閱，本節(jié)不做介紹）。Example Value 是 Swagger 自動(dòng)生成的接口返回信息的模板，這也是接口真正的返回信息。

Response Content Type 是一個(gè)下拉框，表示接口所返回信息的類型，這里是 Swagger 的默認(rèn)設(shè)置，表示返回什么類型的信息都可以。

3.2 第二部分 Parameters

Parameter 列表示接口的請(qǐng)求字段名稱，就是接口的請(qǐng)求值，這里描述的是一個(gè) user 對(duì)象。

Value 列表示請(qǐng)求接口的真實(shí)字段值，就是我要使用這個(gè)接口都需要傳遞哪些參數(shù)。該列還有一個(gè)關(guān)鍵內(nèi)容：Parameter content type ，這是一個(gè)下拉框，表示我們傳遞參數(shù)的請(qǐng)求頭信息，這里的 application/json 表示我們以 json 的形式進(jìn)行傳遞（json 表示什么意思請(qǐng)自行查閱，本節(jié)不做介紹）。

Description 列表示對(duì)接口請(qǐng)求值的描述信息，就是我們?cè)谙蜻@個(gè)接口傳遞參數(shù)的時(shí)候的一些注意事項(xiàng)，這里沒(méi)有描述，所以 Swagger 默認(rèn)使用了字段名稱來(lái)描述。

Parameter Type 列表示接口的請(qǐng)求字段的類型，就是我需要向這個(gè)接口傳遞什么類型的參數(shù)，這里是 body ，表示我們傳遞的請(qǐng)求字段的類型是一個(gè)對(duì)象，這是我們自己設(shè)置的。

Data Type 列表示請(qǐng)求該接口的真實(shí)字段值，就是我要向接口傳遞的具體參數(shù)值，由 Swagger 默認(rèn)生成，和 Value 列相對(duì)應(yīng)，我們可以直接復(fù)制該列的 Example Value 的內(nèi)容粘貼到 Value 列中來(lái)進(jìn)行接口調(diào)試，這樣就不用我們?cè)?Value 列手動(dòng)去輸入字段值了。

3.3 第三部分 Response Messages

HTTP Status Code 列表示接口請(qǐng)求返回的狀態(tài)編碼，不同的編碼會(huì)對(duì)應(yīng)不同的意義，和 Reason 列相對(duì)應(yīng)：201 - 表示已建立接口連接，401 - 表示接口無(wú)權(quán)限訪問(wèn)，403 - 表示接口訪問(wèn)被禁止，404 - 表示在當(dāng)前路徑下找不到該接口，接口無(wú)法返回信息。

• Response Model 列表示我們使用 @Response 注解定義的內(nèi)容，表示接口的響應(yīng)策略，這里只需要知道表示什么意思就行，一般很少使用。

Headers 列表示接口返回信息的響應(yīng)頭類型，這里我們簡(jiǎn)單了解就行。

在左下角有一個(gè) Try it out! 按鈕，該按鈕就是用來(lái)調(diào)試接口的。具體如何調(diào)試接口本節(jié)不做介紹，我會(huì)使用專門(mén)一節(jié)的內(nèi)容來(lái)介紹如何使用 Swagger-UI 進(jìn)行接口調(diào)試。

4. 基于 Swagger-UI 界面的接口調(diào)試

調(diào)試的目的：

我們都知道，在實(shí)際項(xiàng)目開(kāi)發(fā)中，當(dāng)我們的接口開(kāi)發(fā)完畢之后需要進(jìn)行一些必要的自行測(cè)試，目的就是來(lái)看看我們自己所開(kāi)發(fā)的接口有沒(méi)有低級(jí)錯(cuò)誤和基本錯(cuò)誤，在進(jìn)行自測(cè)之前，我們先來(lái)了解一下什么是低級(jí)錯(cuò)誤，什么是基本錯(cuò)誤。

低級(jí)錯(cuò)誤一般是指接口的請(qǐng)求方法沒(méi)有按照接口文檔或者需求來(lái)規(guī)定，對(duì)外暴露的接口地址并不能被請(qǐng)求到。

基本錯(cuò)誤一般是指接口中的參數(shù)類型在開(kāi)發(fā)時(shí)沒(méi)有根據(jù)接口文檔或者需求來(lái)定義，接口的返回?cái)?shù)據(jù)中由于程序引起的返回空值或沒(méi)有返回任何內(nèi)容。

調(diào)試的方法：

在上述內(nèi)容中，我們已經(jīng)對(duì) Swagger-UI 界面進(jìn)行了基本詳細(xì)的介紹。我們以一個(gè)用戶登錄接口為例，來(lái)看看如何在 Swagger-UI 界面上進(jìn)行接口自測(cè)試。

4.1 第一步：找到需要測(cè)試的接口

這一步很簡(jiǎn)單，只需要我們?cè)跒g覽器中輸入 Swagger 生成的 Swagger-UI 界面地址即可，在瀏覽器加載完畢后，我們可以在界面上看到我們項(xiàng)目中的所有接口，在這些接口列表中需要測(cè)試哪個(gè)接口，我們只需要點(diǎn)擊接口名稱即可，如下圖所示：

4.2 第二步：填充參數(shù)并執(zhí)行測(cè)試

針對(duì)接口的內(nèi)容區(qū)域，我們已經(jīng)在上述內(nèi)容中進(jìn)行了詳細(xì)介紹，這里直接步入正題。

點(diǎn)擊接口內(nèi)容區(qū)域的 try it out 按鈕，將鎖定的 Example Value 區(qū)域解鎖，解鎖之后的界面如上圖所示。

• 我們需要在標(biāo)簽 1 的位置填充接口的請(qǐng)求參數(shù)。

• 我們需要在標(biāo)簽 2 的位置選擇請(qǐng)求接口的請(qǐng)求頭類型，一般都為 application/json 類型，這也是 Swagger 默認(rèn)自帶的類型，一般不需要再次選擇。

這里我們就以截圖中的測(cè)試數(shù)據(jù)為例：

{
  "adminPassword": "string",
  "adminUser": "string",
  "createTime": "string",
  "id": 0,
  "updateTime": "string"
}

在兩個(gè)位置的內(nèi)容都填充好之后，我們點(diǎn)擊 Execute 按鈕來(lái)執(zhí)行我們的接口請(qǐng)求。等待片刻之后我們就會(huì)在接口內(nèi)容區(qū)域的最下方看到我們請(qǐng)求所對(duì)應(yīng)的接口響應(yīng)結(jié)果：

• 紅色箭頭指向的地方表明我們已經(jīng)點(diǎn)擊了 Execute 按鈕，即請(qǐng)求已經(jīng)發(fā)送成功了。

• 標(biāo)簽 1 區(qū)域表明接口的請(qǐng)求路徑 Url ，我們可以在這個(gè)地方檢查是否和接口文檔或需求所要求的接口地址一致。

• 標(biāo)簽 2 區(qū)域表明接口的響應(yīng)返回結(jié)果，分為 Code 和 Details 區(qū)域，其中，Code 表明返回狀態(tài)碼，這里是 200 表明接口請(qǐng)求成功，Details 表示請(qǐng)求接口成功時(shí)所返回的響應(yīng)結(jié)果。

接口自測(cè)試總結(jié)

在執(zhí)行完上述兩個(gè)步驟之后，我們就完成了一個(gè)接口的自測(cè)試，通過(guò)在 Swagger-UI 界面上進(jìn)行接口自測(cè)試我們可以很清楚地看到接口的路徑是否正確、接口的請(qǐng)求參數(shù)是否正確、接口的返回結(jié)果是否正確，通過(guò)這種方式我們很好地降低了一個(gè)接口的低級(jí)錯(cuò)誤和基本錯(cuò)誤，這在實(shí)際項(xiàng)目開(kāi)發(fā)中是非常重要的。

5. 小結(jié)

本小節(jié)對(duì) Swagger 三劍客之一 Swagger-UI 生成界面進(jìn)行了詳細(xì)的講解，采用圖文并茂、要點(diǎn)擊破的方式對(duì)生成界面的每一個(gè)基本元素和接口內(nèi)容都做了詳細(xì)的講解和必要的補(bǔ)充，針對(duì)需要重點(diǎn)掌握的內(nèi)容使用了加粗顯示，旨在幫助大家在理解 Swagger-UI 生成界面基本概念的同時(shí)也要懂得如何使用 Swagger-UI 生成界面來(lái)查看接口基本內(nèi)容、接口要點(diǎn)信息等。

在介紹完 Swagger-UI 生成界面的基本元素以及接口基本內(nèi)容區(qū)域之后，我們還結(jié)合一個(gè)用戶登錄接口就如何基于 Swagger-UI 生成界面進(jìn)行接口調(diào)試做了詳細(xì)的介紹，通過(guò)分步實(shí)現(xiàn)的順序?qū)γ恳徊襟E中需要注意的地方單獨(dú)做了講解。

希望各位同學(xué)在學(xué)習(xí)本小節(jié)內(nèi)容時(shí)可以結(jié)合自己的項(xiàng)目或者自己創(chuàng)建的 Demo 案例來(lái)學(xué)習(xí)，這是掌握本節(jié)內(nèi)容最好最快的方式。