Spring Boot 整合 Swagger2，構建強大的 API 文件

村雨遙發表於2022-01-12
Spring BootSwaggerAPI

前言

不管你是從事前端還是後端開發，相信都難免被介面文件折磨過。如果你是一個前端開發者，可能你會經常發現後端給的介面文件跟實際程式碼有所出入。而假設你是一個後端開發者，你可能又會覺得自己開發後端介面已經夠煩的了，還要花費大量精力去編寫和維護介面文件，所以難免有時候會更新不及時。這就可能造成了前後端相互不理解，最後甚至吵起來，哈哈哈 ?。

這時候我們就會想，有沒有一款工具，能讓我們快速實現編寫介面文件。這個工具既能保證我們的介面文件實時更新，也能保證我們不用花過多時間去維護，就像寫註釋那麼簡單。

既然這是大多數前後端程式設計師的一大痛點，那必須得有一個解決方案吧。而這個方案使用的人多了，慢慢就成了一種規範，大家都預設使用這個方案，從而解決前後端介面文件不同步的問題，而這就是我們今天的主角 - Swagger 的由來。

通過使用 Swagger，我們只需要按照它所給定的一系列規範去定義介面以及介面的相關資訊，然後它就能幫我們自動生成各種格式的介面文件，方便前後端開發者進行前後端聯調。同時，如果我們的程式碼介面有所變動，只需要更新 Swagger 的描述，它就能進行實時更新，做到實際程式碼和介面文件的一致性。

Swagger 簡介

Swagger 是什麼

Swagger 是一種介面描述語言，主要用於生成、描述、呼叫以及視覺化 RESTful 風格的 Web 服務介面文件。以前的專案可能更多的是前後端未分開同時進行開發，所以介面文件可能不是那麼重要。但現在主流的專案基本都是前後端分離，如果前後端沒有溝通好，就有可能導致介面文件更新不及時，造成一些不必要的麻煩。而通俗地講，Swagger 就是幫我們寫介面文件的。它不僅能自動生成實時介面文件，還能生成測試用例，方便我們進行測試。

Swagger 主要提供瞭如下幾種開源工具：

  1. Swagger Editor

Swagger 所提供的的編輯器，主要用於編輯 Swagger 描述檔案，支援實時預覽描述檔案更新後的效果，類似於我們的 Markdown 編輯器，左邊編寫原始碼，右邊就可以進行實時預覽。該編輯器不僅提供線上使用，還支援本地部署。

  1. Swagger UI

提供視覺化的 UI 頁面，用於展示 Swagger 的描述檔案。介面的呼叫方、測試等都可以通過該頁面查閱介面的相關資訊，並且進行簡單的介面請求測試。

  1. Swagger Codegen

通過使用該工具，可以將 Swagger 的描述檔案生成 HTML 和 CWIKI 形式的介面文件，而且還能生成針對多種不同語言的服務端和客戶端的程式碼。

Swagger UI

平時和我們打交道最多的，可能就是 Swagger UI 這個工具了，它主要用於顯示介面文件。根據我們程式碼中按照 Swagger 規範所設定的描述，自動生成介面說明文件。一個簡單的示例如下：

Spring Boot 整合 Swagger

建立 Spring Boot 專案

通過以上對 Swagger 簡單的介紹之後，我們來看看如何在 Spring Boot 專案中使用 Swagger。

首先需要建立一個簡單的 Spring Boot 專案，如果你還不知道如何建立，可以參考我之前的一篇文章 建立 Spring Boot 專案的 3 種方式。

建立好之後的專案介面如下：

image-20220105220626619

引入依賴

建立好 Spring Boot 專案之後，需要配置專案 pom.xml 檔案，在其中引入 Swagger 的相關依賴。

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

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

構建 Swagger 配置類

引入依賴後，接下來就是構建 Swagger 的配置類了。

package com.cunyu.springbootswaggerdemo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;

import java.util.ArrayList;

/**
 * Created with IntelliJ IDEA.
 *
 * @author : 村雨遙
 * @version : 1.0
 * @project : springboot-swagger-demo
 * @package : com.cunyu.springbootswaggerdemo.config
 * @className : Swagger2Configuration
 * @createTime : 2022/1/5 22:21
 * @email : 747731461@qq.com
 * @微信 : cunyu1024
 * @公眾號 : 村雨遙
 * @網站 : https://cunyu1943.github.io
 * @description :
 */
@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    /**
     * 配置 Swagger 2
     * 註冊一個 Bean 屬性
     * enable()：是否啟用 Swagger，啟用後才能在瀏覽器中進行訪問
     * groupName()：用於配置 API 文件的分組
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)
                .groupName("v1")
                .select()
                // 過濾路徑
                //.paths(PathSelectors.ant())
                // 指定掃描的包
                .apis(RequestHandlerSelectors.basePackage("com.cunyu.springbootswaggerdemo.controller"))
                .build();
    }

    private ApiInfo apiInfo() {
        /*作者資訊*/
        Contact contact = new Contact("村雨遙", "https://cunyu1943.github.io", "747731461@qq.com");
        return new ApiInfo(
                "Swagger 測試介面文件",
                "Spring Boot 整合 Swagger 測試介面文件",
                "v1.0",
                "https://cunyu1943.github.io",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList()
        );
    }
}

編寫介面

配置好 Swagger 後，在我們的專案中新增一個簡單的介面，這裡以一個簡單的有參和無參介面為例。

package com.cunyu.springbootswaggerdemo.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * Created with IntelliJ IDEA.
 *
 * @author : 村雨遙
 * @version : 1.0
 * @project : springboot-swagger-demo
 * @package : com.cunyu.springbootswaggerdemo.controller
 * @className : SwaggerDemoController
 * @createTime : 2022/1/5 22:21
 * @email : 747731461@qq.com
 * @微信 : cunyu1024
 * @公眾號 : 村雨遙
 * @網站 : https://cunyu1943.github.io
 * @description :
 */

@Api
@RestController
public class SwaggerDemoController {
    @ApiOperation(value = "hello world 介面")
    @GetMapping("hello")
    public String hello() {
        return "hello world";
    }

    @ApiOperation(value = "有參介面")
    @PostMapping("demo")
    public String demo(@ApiParam(name = "name", value = "村雨遙", required = true) String name) {
        return "hello," + name;
    }
}

檢視並測試介面

完成上述步驟後，我們啟動專案，然後在瀏覽器中訪問如下地址，就可以訪問我們專案的介面文件了。

http://localhost:8080/swagger...

訪問如上地址後，如果出現下面的介面，說明我們 Spring Boot 整合 Swagger2 就到此成功了。

點開具體的介面，就會有這個介面的一些詳細資訊，如下圖所示，一般包括：

  1. 介面請求方式
  2. 介面請求路徑及描述
  3. 介面請求引數
  4. 介面響應

如果我們要進行簡單的測試，則點選上圖中右上方的 Try it out，然後我們就可以編輯請求引數的值，編輯完成之後點選下方的 Execute 即可檢視介面返回值。

以我給的介面為例，我傳入了一個引數 name，然後執行 demo 介面，最後會給我返回 hello,name 的結果，其中 name 是我傳入的引數值，這裡我傳入了村雨遙，所以結果應該會得到 hello,村雨遙，可以看到 Swagger 測試中也給我返回了對應的結果，說明我們的介面測試成功！

注意

如果在整合過程中出現如下錯誤：

org.springframework.context.ApplicationContextException:Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

這裡可能是由於 Spring Boot 版本過高導致，我寫作本文時，一開始使用的 SpringBoot 2.6.2 版本，所以出現了該錯誤，而當我將 SpringBoot 降級為 2.5.6 時，該錯誤就不再出現。所以如果你也出現了這個問題，也可以嘗試降低 SpringBoot 版本來解決。

總結

以上就是本文的所有內容了，主要對 Swagger 進行了簡單介紹，並用 Spring Boot 整合 Swagger，並進行簡單的測試。而關於文章中的示例程式碼，我已經上傳到了 Github，如果有需要的朋友，可以自取。

傳送門：https://github.com/cunyu1943/...

相關文章