SpringBoot整合超好用的API視覺化介面工具swagger

# SpringBoot整合-超好用的API視覺化介面工具swagger

一、簡介

Swagger 是一個規範和完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。總體目標是使客戶端和檔案系統作為伺服器以同樣的速度來更新。檔案的方法，引數和模型緊密整合到伺服器端的程式碼，允許API來始終保持同步。

作用：

1. 介面的文件線上自動生成。
2. 功能測試。

Swagger是一組開源專案，其中主要要專案如下：

Swagger-tools:提供各種與Swagger進行整合和互動的工具。例如模式檢驗、Swagger 1.2文件轉換成Swagger 2.0文件等功能。

---

Swagger-core: 用於Java/Scala的的Swagger實現。與JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架進行整合。

---

Swagger-js: 用於JavaScript的Swagger實現。

---

Swagger-node-express: Swagger模組，用於node.js的Express web應用框架。

---

Swagger-ui：一個無依賴的HTML、JS和CSS集合，可以為Swagger相容API動態生成優雅文件。

---

Swagger-codegen：一個模板驅動引擎，通過分析使用者Swagger資源宣告以各種語言生成客戶端程式碼。

二、使用第三方依賴（最簡單的方法）

這時對swagger的再封裝：

1、在pom.xml檔案中新增第三方swagger依賴（）

<dependency>
	<groupId>com.spring4all</groupId>
	<artifactId>swagger-spring-boot-starter</artifactId>
	<version>1.7.0.RELEASE</version>
</dependency>

2、在Spring Boot專案的啟動類上新增@EnableSwagger2Doc註解，就可以直接使用啦。
3、https://gitee.com/didispace/spring-boot-starter-swagger這是碼雲上這個swagger依賴實現的專案，裡面有詳細的講解。

---

下面是官方推薦使用的：

三、Springboot整合swagger

1.匯入依賴

1.引入架包 （記得切換匹配的版本），本文采用1.5.2.RELEASE的Springboot版本。

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<!-- 匯入swagger依賴 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>

2.新建一個swagger的啟動類

2.新建swagger2類，和啟動類平行目錄，如圖。

3.編寫Swagger2程式碼

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2配置類
 * 在與spring boot整合時，放在與Application.java同級的目錄下。
 * 通過@Configuration註解，讓Spring來載入該類配置。
 * 再通過@EnableSwagger2註解來啟用Swagger2。
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    /**
     * 建立API應用
     * apiInfo() 增加API相關資訊
     * 通過select()函式返回一個ApiSelectorBuilder例項,用來控制哪些介面暴露給Swagger來展現，
     * 本例採用指定掃描的包路徑來定義指定要建立API的目錄。
     * 
     * @return
     */
    //swagger2的配置檔案，這裡可以配置swagger2的一些基本的內容，比如掃描的包等等
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //為當前包路徑
            .apis(RequestHandlerSelectors.basePackage("com.zhang.myblog.controller"))
            .paths(PathSelectors.any())
            .build();
    }

    /**
     * 建立該API的基本資訊（這些基本資訊會展現在文件頁面中）
     * 訪問地址：http://專案實際地址/swagger-ui.html
     * @return
     */
    //構建 api文件的詳細資訊函式,注意這裡的註解引用的是哪個
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            //頁面標題
            .title("Spring Boot 測試使用 Swagger2 構建RESTful API")
            //建立人
            .contact(new Contact("吳偉俊", "http://www.gitee.com/zzwuweijun", "1227297881@qq.com"))
            //版本號
            .version("1.0")
            //描述
            .description("API 描述")
            .description("更多請關注http://www.baidu.com")
            // // 給定一個網址，可以是自己專案的首頁等等；在swagger的首頁處有一個連線：Terms of service
            .termsOfServiceUrl("http://www.baidu.com")
            .build();
    }
}

4.使用

在專案的完整URL上，加上 swagger-ui.html例如：

輸入網址http://localhost:8080/swagger-ui.html。

---

四、使用swagger註解

@Api

用在類上，該註解將一個Controller（Class）標註為一個swagger資源（API）。在預設情況下，Swagger-Core只會掃描解析具有@Api註解的類，而會自動忽略其他類別資源（JAX-RS endpoints，Servlets等等）的註解。該註解包含以下幾個重要屬性

• tags API分組標籤。具有相同標籤的API將會被歸併在一組內展示。
• value 如果tags沒有定義，value將作為Api的tags使用
• description API的詳細描述，在1.5.X版本之後不再使用，但實際發現在2.0.0版本中仍然可以使用

屬性名稱	備註
value	url的路徑值
tags	如果設定這個值、value的值會被覆蓋
description	對api資源的描述
basePath	基本路徑可以不配置
position	如果配置多個Api 想改變顯示的順序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高階特性認證時配置
hidden	配置為true 將在文件中隱藏

例子：

package com.wwj.helloworldquick.controller;
// ....
@Api(tags = {"one2"}, description = "對TestSwagger2類的說明")
@RestController
public class TestSwagger2 {
   @GetMapping("/swagger2")
   public String swagger() {// 無參
       return "swagger";
   }
}

---

@ApiOperation

在指定的（路由）路徑上，對一個操作或HTTP方法進行描述。具有相同路徑的不同操作會被歸組為同一個操作物件。不同的HTTP請求方法及路徑組合構成一個唯一操作。此註解的屬性有：

• value 對操作的簡單說明，長度為120個字母，60個漢字。
• notes 對操作的詳細說明。使用字串 "\n"可以換行。
• httpMethod HTTP請求的動作名，可選值有：“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”。注意，這裡最好是大寫。
• code 預設為200，有效值必須符合標準的HTTP Status Code Definitions。
• response 返回的物件

屬性名稱	備註
value	url的路徑值
notes	對操作的詳細說明。
tags	如果設定這個值、value的值會被覆蓋
description	對api資源的描述
basePath	基本路徑可以不配置
position	如果配置多個Api 想改變顯示的順序位置
produces	For example, “application/json, application/xml”
consumes	For example, “application/json, application/xml”
protocols	Possible values: http, https, ws, wss.
authorizations	高階特性認證時配置
hidden	配置為true 將在文件中隱藏
response	返回的物件
responseContainer	這些物件是有效的 “List”, “Set” or “Map”.，其他無效
httpMethod	“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”
code	http的狀態碼 預設 200
extensions	擴充套件屬性

例子：

@Api(tags = {"one2"}, description = "對TestSwagger2類的說明")
@RestController
public class TestSwagger2 {
    @GetMapping("/swagger2")
    @ApiOperation(value = "訪問/swagger，簡單說明2", notes = "詳細說明：訪問/swagger，簡單說明2",
                  httpMethod = "GET", code = 200, response = Person.class)
    public String swagger() {// 無參
        return "swagger";
    }
}

---

@ApiImplicitParams

用在方法上，註解ApiImplicitParam的容器類，以陣列方式儲存。

@ApiImplicitParams：用在請求的方法上，表示一組引數說明
    @ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求引數的各個方面
        name：引數名
        value：引數的漢字說明、解釋
        required：引數是否必須傳
        paramType：引數放在哪個地方
            · header --> 請求引數的獲取：@RequestHeader
            · query --> 請求引數的獲取：@RequestParam
            · path（用於restful介面）--> 請求引數的獲取：@PathVariable
            · body（不常用）
            · form（不常用）    
        dataType：引數型別，預設String，其它值dataType="Integer"       
        defaultValue：引數的預設值

@ApiImplicitParam

對API的單一引數進行註解。雖然註解@ApiParam同JAX-RS引數相繫結，但這個@ApiImplicitParam註解可以以統一的方式定義引數列表，也是在Servelet及非JAX-RS環境下，唯一的方式引數定義方式。注意這個註解@ApiImplicitParam必須被包含在註解@ApiImplicitParams之內。可以設定以下重要引數屬性：

• name 引數名稱
• value 引數的簡短描述
• required 是否為必傳引數
• dataType 引數型別，可以為類名，也可以為基本型別（String，int、boolean等）
• paramType 引數的傳入（請求）型別，可選的值有path, query, body, header or form。
• defaultValue：引數的預設值

例子：

@Api(tags = {"one2"}, description = "對TestSwagger2類的說明")
@RestController
public class TestSwagger2 {
    //@GetMapping("/swagger2")
    @RequestMapping("/swagger2")
    @ApiOperation(value = "訪問/swagger，簡單說明2", notes = "詳細說明：訪問/swagger，簡單說明2",
                  httpMethod = "GET", code = 200, response = Person.class)
    
    @ApiImplicitParams({
        @ApiImplicitParam(value = "使用者名稱", name = "name", required = true, dataTypeClass = String.class, paramType = "query"),
        @ApiImplicitParam(value = "使用者年齡", name = "age", required = true, dataType = "int", paramType = "path")
    })
    public String swagger(String name, Integer age) {
        return "swagger";
    }
}

---

@ApiParam

增加對引數的元資訊說明。這個註解只能被使用在JAX-RS 1.x/2.x的綜合環境下。其主要的屬性有

• required 是否為必傳引數
• value 引數簡短說明

屬性名稱	備註
name	屬性名稱
value	屬性值
defaultValue	預設屬性值
allowableValues	可以不配置
required	是否屬性必填
access	不過多描述
allowMultiple	預設為false
hidden	隱藏該屬性
example	舉例子

@ApiResponses

註解@ApiResponse的包裝類，陣列結構。即使需要使用一個@ApiResponse註解，也需要將@ApiResponse註解包含在註解@ApiResponses內。

@ApiResponse

描述一個操作可能的返回結果。當REST API請求發生時，這個註解可用於描述所有可能的成功與錯誤碼。可以用，也可以不用這個註解去描述操作的返回型別，但成功操作的返回型別必須在@ApiOperation中定義。如果API具有不同的返回型別，那麼需要分別定義返回值，並將返回型別進行關聯。但Swagger不支援同一返回碼，多種返回型別的註解。注意：這個註解必須被包含在@ApiResponses註解中。

• code HTTP請求返回碼。有效值必須符合標準的HTTP Status Code Definitions。
• message 更加易於理解的文字訊息
• response 返回型別資訊，必須使用完全限定類名，比如“com.xyz.cc.Person.class”。
• responseContainer 如果返回型別為容器型別，可以設定相應的值。有效值為 “List”, “Set” or “Map”，其他任何無效的值都會被忽略。

@Api(tags = {"one2"}, description = "對TestSwagger2類的說明")
@RestController
public class TestSwagger2 {
    //@GetMapping("/swagger2")
    @RequestMapping("/swagger2")
    @ApiOperation(value = "訪問/swagger，簡單說明2", notes = "詳細說明：訪問/swagger，簡單說明2",
                  httpMethod = "GET", code = 200, response = Person.class)
    @ApiImplicitParams({
        @ApiImplicitParam(value = "使用者名稱", name = "name", required = true, dataTypeClass = String.class, paramType = "query"),
        @ApiImplicitParam(value = "使用者年齡", name = "age", required = true, dataType = "int", paramType = "path")})

    @ApiResponses({
        @ApiResponse(code = 200, message = "成功返回，返回值型別為Person型別--》", response = Person.class),
        @ApiResponse(code = 404, message = "請求錯誤，都返回-1", response = Integer.class)
    })
    public String swagger(String name, Integer age) {
        return "swagger";
    }
}

---

---

對於Model的註解，Swagger提供了兩個：@ApiModel及@ApiModelProperty，分別用以描述Model及Model內的屬性。

@ApiModel

描述一個Model的資訊（一般用在請求引數無法使用@ApiImplicitParam註解進行描述的時候）

提供對Swagger model額外資訊的描述。在標註@ApiOperation註解的操作內，所有的類將自動被內省（introspected），但利用這個註解可以做一些更加詳細的model結構說明。主要屬性有：

• value model的別名，預設為類名
• description model的詳細描述

@ApiModelProperty

描述一個model的屬性

對model屬性的註解，主要的屬性值有：

• value 屬性簡短描述
• example 屬性的示例值
• required 是否為必須值

@ApiIgnore

可以標誌在類上和方法，都表示忽略。

五、美化介面

美化介面：
在maven中新增以下架包，採用別人封裝的美化swagger介面架包。

<!-- 上面兩個jar的必須的，下面這個是第三方的UI介面的美化，不是必需的 -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.6</version>
</dependency>

在配置類和啟動類都需要新增@EnableSwagger2註解。
————————————————

測試沒起作用。。。。尷尬

六、報錯

關於Swagger報錯java.lang.NumberFormatException: For input string: ""的總結

https://blog.csdn.net/qq122516902/article/details/89673363

發現一種解決方法：在註解@ApiImplicitParam的example屬性設定一個值就好了。

七、陣列/集合引數的正確配置方式allowMultiple、dataType

轉自：https://blog.csdn.net/hanchao5272/article/details/99729606?depth_1-utm_source=distribute.pc_relevant.none-task&utm_source=distribute.pc_relevant.none-task

---

介面引數的註解配置

// GET引數
@ApiImplicitParam(name = "list", value = "使用者ID列表", paramType = "query", allowMultiple = true, dataType = "int")

// POST引數
@ApiImplicitParam(name = "list", value = "使用者名稱稱列表", paramType = "body", allowMultiple = true, dataType = "String")

// POST引數-自定義型別User
@ApiImplicitParam(name = "list", value = "使用者列表", paramType = "body", allowMultiple = true, dataType = "UserDto")

主要引數：

• allowMultiple：允許多個，即：陣列或集合。
• dataType：陣列或集合的元素型別，即：類名。

自定義型別的註解配置

@ApiModel(value = "UserDto", description = "使用者")
public class User implements Serializable {
  //...
}

特別的：

• 如果元素型別為原生型別，如：int、String之類的，無需此步驟。
• 如果元素型別為自定義型別，如：UserDto，則必須此步驟，以便swagger能夠找到這個元素對應的型別。