前言：

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

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

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

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

一、Swagger 是什么

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

Swagger 主要提供了如下幾種開(kāi)源工具：

1.Swagger Editor

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

2.Swagger UI

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

3.Swagger Codegen

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

4.Swagger UI

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

二、Spring Boot 集成 Swagger

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

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

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

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

2.引入依賴(lài)

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

<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 配置類(lèi)

引入依賴(lài)后，接下來(lái)就是構(gòu)建 Swagger 的配置類(lèi)了。

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)行訪(fǎng)問(wèn)
? ? ?* groupName()：用于配置 API 文檔的分組
? ? ?*/
? ? @Bean
? ? public Docket docket() {
? ? ? ? return new Docket(DocumentationType.SWAGGER_2)
? ? ? ? ? ? ? ? .apiInfo(apiInfo())
? ? ? ? ? ? ? ? .enable(true)
? ? ? ? ? ? ? ? .groupName("v1")
? ? ? ? ? ? ? ? .select()
? ? ? ? ? ? ? ? // 過(guò)濾路徑
? ? ? ? ? ? ? ? //.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 測(cè)試接口文檔",
? ? ? ? ? ? ? ? "Spring Boot 集成 Swagger 測(cè)試接口文檔",
? ? ? ? ? ? ? ? "v1.0",
? ? ? ? ? ? ? ? "https://cunyu1943.github.io",
? ? ? ? ? ? ? ? contact,
? ? ? ? ? ? ? ? "Apache 2.0",
? ? ? ? ? ? ? ? "http://www.apache.org/licenses/LICENSE-2.0",
? ? ? ? ? ? ? ? new ArrayList()
? ? ? ? );
? ? }
}

4.編寫(xiě)接口

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

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

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

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

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

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

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

如果我們要進(jìn)行簡(jiǎn)單的測(cè)試，則點(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 測(cè)試中也給我返回了對(duì)應(yīng)的結(jié)果，說(shuō)明我們的接口測(cè)試成功！

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

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

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

總結(jié)：

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

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

最新評(píng)論