前言：

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

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

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

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

一、Swagger 是什么

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

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

1.Swagger Editor

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

2.Swagger UI

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

3.Swagger Codegen

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

4.Swagger UI

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

二、Spring Boot 集成 Swagger

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

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

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

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

2.引入依賴

創(chuàng)建好Spring Boot 項(xiàng)目之后，需要配置項(xiàng)目 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
? ? ?* 注冊(cè)一個(gè) 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", "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 后，在我們的項(xiàng)目中添加一個(gè)簡單的接口，這里以一個(gè)簡單的有參和無參接口為例。

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.查看并測試接口

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

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

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

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

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

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

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

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

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

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

總結(jié)：

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

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

最新評(píng)論