前言：

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

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

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

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

一、Swagger 是什么

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

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

1.Swagger Editor

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

2.Swagger UI

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

3.Swagger Codegen

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

4.Swagger UI

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

二、Spring Boot 集成 Swagger

1.創(chuàng)建 Spring Boot 項目

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

首先需要創(chuàng)建一個簡單的 Spring Boot 項目，如果你還不知道如何創(chuàng)建，可以參考Spring Boot 教程之創(chuàng)建項目的三種方式

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

2.引入依賴

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

<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.構(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;

@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;


@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

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

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

• 接口請求方式
• 接口請求路徑及描述
• 接口請求參數(shù)
• 接口響應(yīng)

如果我們要進行簡單的測試，則點擊上圖中右上方的 Try it out，然后我們就可以編輯請求參數(shù)的值，編輯完成之后點擊下方的 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 版本過高導致，我寫作本文時，一開始使用的 SpringBoot 2.6.2 版本，所以出現(xiàn)了該錯誤，而當我將 SpringBoot 降級為 2.5.6 時，該錯誤就不再出現(xiàn)。所以如果你也出現(xiàn)了這個問題，也可以嘗試降低 SpringBoot 版本來解決。

總結(jié)：

以上就是本文的所有內(nèi)容了，主要對 Swagger 進行了簡單介紹，并用 Spring Boot 集成 Swagger，同時還進行簡單的測試。

到此這篇關(guān)于Spring Boot 集成 Swagger2構(gòu)建 API文檔的文章就介紹到這了,更多相關(guān)構(gòu)建 API文檔內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評論