Spring Boot 集成 Swagger2，構(gòu)建強(qiáng)大的 API 文檔

本文已收錄至：https://cunyu1943.blog.csdn.net/

前言

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

這時候我們就會想，有沒有一款工具，能讓我們快速實(shí)現(xiàn)編寫接口文檔。這個工具既能保證我們的接口文檔實(shí)時更新，也能保證我們不用花過多時間去維護(hù)，就像寫注釋那么簡單。

既然這是大多數(shù)前后端程序員的一大痛點(diǎn)，那必須得有一個解決方案吧。而這個方案使用的人多了，慢慢就成了一種規(guī)范，大家都默認(rèn)使用這個方案，從而解決前后端接口文檔不同步的問題，而這就是我們今天的主角 - Swagger 的由來。

通過使用 Swagger，我們只需要按照它所給定的一系列規(guī)范去定義接口以及接口的相關(guān)信息，然后它就能幫我們自動生成各種格式的接口文檔，方便前后端開發(fā)者進(jìn)行前后端聯(lián)調(diào)。同時，如果我們的代碼接口有所變動，只需要更新 Swagger 的描述，它就能進(jìn)行實(shí)時更新，做到實(shí)際代碼和接口文檔的一致性。

Swagger 簡介

Swagger 是什么

Swagger 是一種接口描述語言，主要用于生成、描述、調(diào)用以及可視化 RESTful 風(fēng)格的 Web 服務(wù)接口文檔。以前的項(xiàng)目可能更多的是前后端未分開同時進(jìn)行開發(fā)，所以接口文檔可能不是那么重要。但現(xiàn)在主流的項(xiàng)目基本都是前后端分離，如果前后端沒有溝通好，就有可能導(dǎo)致接口文檔更新不及時，造成一些不必要的麻煩。而通俗地講，Swagger 就是幫我們寫接口文檔的。它不僅能自動生成實(shí)時接口文檔，還能生成測試用例，方便我們進(jìn)行測試。

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

1. Swagger Editor

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

2. Swagger UI

提供可視化的 UI 頁面，用于展示 Swagger 的描述文件。接口的調(diào)用方、測試等都可以通過該頁面查閱接口的相關(guān)信息，并且進(jìn)行簡單的接口請求測試。

3. Swagger Codegen

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

Swagger UI

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

Spring Boot 集成 Swagger

創(chuàng)建 Spring Boot 項(xiàng)目

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

首先需要創(chuàng)建一個簡單的 Spring Boot 項(xiàng)目，如果你還不知道如何創(chuàng)建，可以參考我之前的一篇文章 創(chuàng)建 Spring Boot 項(xiàng)目的 3 種方式^[1]。

創(chuàng)建好之后的項(xiàng)目接口如下：

引入依賴

創(chuàng)建好 Spring Boot 項(xiàng)目之后，需要配置項(xiàng)目 pom.xml 文件，在其中引入 Swagger 的相關(guān)依賴。

<dependency>
????<groupId>io.springfoxgroupId>
????<artifactId>springfox-swagger2artifactId>
????<version>2.9.2version>
dependency>

<dependency>
????<groupId>io.springfoxgroupId>
????<artifactId>springfox-swagger-uiartifactId>
????<version>2.9.2version>
dependency>

構(gòu)建 Swagger 配置類

引入依賴后，接下來就是構(gòu)建 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
?*?@公眾號?:?村雨遙
?*?@網(wǎng)站?:?https://cunyu1943.github.io
?*?@description?:
?*/
@Configuration
@EnableSwagger2
public?class?Swagger2Configuration?{

????/**
?????*?配置?Swagger?2
?????*?注冊一個?Bean?屬性
?????* enable()：是否啟用 Swagger，啟用后才能在瀏覽器中進(jìn)行訪問
?????* 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()
????????);
????}
}

編寫接口

配置好 Swagger 后，在我們的項(xiàng)目中添加一個簡單的接口，這里以一個簡單的有參和無參接口為例。

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
?*?@公眾號?:?村雨遙
?*?@網(wǎng)站?:?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;
????}
}

查看并測試接口

完成上述步驟后，我們啟動項(xiàng)目，然后在瀏覽器中訪問如下地址，就可以訪問我們項(xiàng)目的接口文檔了。

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

訪問如上地址后，如果出現(xiàn)下面的界面，說明我們 Spring Boot 集成 Swagger2 就到此成功了。

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

1. 接口請求方式
2. 接口請求路徑及描述
3. 接口請求參數(shù)
4. 接口響應(yīng)

如果我們要進(jìn)行簡單的測試，則點(diǎn)擊上圖中右上方的 Try it out，然后我們就可以編輯請求參數(shù)的值，編輯完成之后點(diǎn)擊下方的 Execute 即可查看接口返回值。

以我給的接口為例，我傳入了一個參數(shù) name，然后執(zhí)行 demo 接口，最后會給我返回 hello,name 的結(jié)果，其中 name 是我傳入的參數(shù)值，這里我傳入了村雨遙，所以結(jié)果應(yīng)該會得到 hello,村雨遙，可以看到 Swagger 測試中也給我返回了對應(yīng)的結(jié)果，說明我們的接口測試成功！

注意

如果在整合過程中出現(xiàn)如下錯誤：

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

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

總結(jié)

以上就是本文的所有內(nèi)容了，主要對 Swagger 進(jìn)行了簡單介紹，并用 Spring Boot 集成 Swagger，同時還進(jìn)行簡單的測試。而關(guān)于文章中的示例代碼，我已經(jīng)上傳到了 Github，如果有需要的朋友，可以自取。

傳送門：https://github.com/cunyu1943/java-learning-demos

參考資料