Spring Boot 集成 Swagger2構建 API文檔

Posted on by

前言：

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

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

既然這是大多數前後端程序員的一大痛點，那必須得有一個解決方案吧。而這個方案使用的人多瞭，慢慢就成瞭一種規范，大傢都默認使用這個方案，從而解決前後端接口文檔不同步的問題，而這就是我們今天的主角 – Swagger 的由來。

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

一、Swagger 是什麼

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

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

1.Swagger Editor

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

2.Swagger UI

提供可視化的 UI 頁面，用於展示 Swagger 的描述文件。接口的調用方、測試等都可以通過該頁面查閱接口的相關信息，並且進行簡單的接口請求測試。

3.Swagger Codegen

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

4.Swagger UI

平時和我們打交道最多的，可能就是 Swagger UI 這個工具瞭，它主要用於顯示接口文檔。根據我們代碼中按照 Swagger 規范所設置的描述，自動生成接口說明文檔。一個簡單的示例如下：

二、Spring Boot 集成 Swagger

1.創建 Spring Boot 項目

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

首先需要創建一個簡單的 Spring Boot 項目，如果你還不知道如何創建，

創建好之後的項目接口如下：

2.引入依賴

創建好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>

3.構建 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 : [email protected]
 * @微信 : 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", "[email protected]");
        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()
        );
    }
}

4.編寫接口

配置好 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 : [email protected]
 * @微信 : 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;
    }
}

5.查看並測試接口

完成上述步驟後，我們啟動項目，然後在瀏覽器中訪問如下地址，就可以訪問我們項目的接口文檔瞭。

http://localhost:8080/swagger-ui.html

訪問如上地址後，如果出現下面的界面，說明我們 Spring Boot 集成 Swagger2 就到此成功瞭。

點開具體的接口，就會有這個接口的一些詳細信息，如下圖所示，一般包括：

  • 接口請求方式
  • 接口請求路徑及描述
  • 接口請求參數
  • 接口響應

如果我們要進行簡單的測試，則點擊上圖中右上方的 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，同時還進行簡單的測試。

到此這篇關於Spring Boot 集成 Swagger2構建 API文檔的文章就介紹到這瞭,更多相關構建 API文檔內容請搜索WalkonNet以前的文章或繼續瀏覽下面的相關文章希望大傢以後多多支持WalkonNet！

推薦閱讀：