Spring?Boot集成Swagger2怎么構建API文檔

這篇文章主要講解了“Spring Boot集成Swagger2怎么構建API文檔”，文中的講解內容簡單清晰，易于學習與理解，下面請大家跟著小編的思路慢慢深入，一起來研究和學習“Spring Boot集成Swagger2怎么構建API文檔”吧！

一、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 : 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()
        );
    }
}

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 : 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;
    }
}

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 版本來解決。

感謝各位的閱讀，以上就是“Spring Boot集成Swagger2怎么構建API文檔”的內容了，經過本文的學習后，相信大家對Spring Boot集成Swagger2怎么構建API文檔這一問題有了更深刻的體會，具體使用情況還需要大家實踐驗證。這里是億速云，小編將為大家推送更多相關知識點的文章，歡迎關注！