Swagger-UI 生成界面使用詳解

1. 前言

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

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

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

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

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

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

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

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

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

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

我們從上到下，依次進行介紹：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3.1 第一部分 Response Class

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

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

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

3.2 第二部分 Parameters

Parameter 列表示接口的請求字段名稱，就是接口的請求值，這里描述的是一個 user 對象。

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

Description 列表示對接口請求值的描述信息，就是我們在向這個接口傳遞參數(shù)的時候的一些注意事項，這里沒有描述，所以 Swagger 默認使用了字段名稱來描述。

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

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

3.3 第三部分 Response Messages

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

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

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

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

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

調(diào)試的目的：

我們都知道，在實際項目開發(fā)中，當我們的接口開發(fā)完畢之后需要進行一些必要的自行測試，目的就是來看看我們自己所開發(fā)的接口有沒有低級錯誤和基本錯誤，在進行自測之前，我們先來了解一下什么是低級錯誤，什么是基本錯誤。

低級錯誤一般是指接口的請求方法沒有按照接口文檔或者需求來規(guī)定，對外暴露的接口地址并不能被請求到。

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

調(diào)試的方法：

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

4.1 第一步：找到需要測試的接口

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

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

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

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

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

• 我們需要在標簽 2 的位置選擇請求接口的請求頭類型，一般都為 application/json 類型，這也是 Swagger 默認自帶的類型，一般不需要再次選擇。

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

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

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

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

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

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

接口自測試總結(jié)

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

5. 小結(jié)

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

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

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