前言

Spring Boot 框架是目前非常流行的微服務(wù)框架，我們很多情況下使用它來(lái)提供 Rest API。而對(duì)于 Rest API 來(lái)說(shuō)很重要的一部分內(nèi)容就是文檔，Swagger 為我們提供了一套通過(guò)代碼和注解自動(dòng)生成文檔的方法，這一點(diǎn)對(duì)于保證 API 文檔的及時(shí)性將有很大的幫助。本文將使用 Swagger 2 規(guī)范的 Springfox 實(shí)現(xiàn)來(lái)了解如何在 Spring Boot 項(xiàng)目中使用 Swagger，主要包含了如何使用 Swagger 自動(dòng)生成文檔、使用 Swagger 文檔以及 Swagger 相關(guān)的一些高級(jí)配置和注解。

Swagger 簡(jiǎn)介

Swagger 是一套基于 OpenAPI 規(guī)范構(gòu)建的開(kāi)源工具，可以幫助我們?cè)O(shè)計(jì)、構(gòu)建、記錄以及使用 Rest API。Swagger 主要包含了以下三個(gè)部分：

Swagger Editor：基于瀏覽器的編輯器，我們可以使用它編寫(xiě)我們 OpenAPI 規(guī)范。

Swagger UI：它會(huì)將我們編寫(xiě)的 OpenAPI 規(guī)范呈現(xiàn)為交互式的 API 文檔，后文我將使用瀏覽器來(lái)查看并且操作我們的 Rest API。

Swagger Codegen：它可以通過(guò)為 OpenAPI（以前稱為 Swagger）規(guī)范定義的任何 API 生成服務(wù)器存根和客戶端 SDK 來(lái)簡(jiǎn)化構(gòu)建過(guò)程。

為什么要使用 Swagger

當(dāng)下很多公司都采取前后端分離的開(kāi)發(fā)模式，前端和后端的工作由不同的工程師完成。在這種開(kāi)發(fā)模式下，維持一份及時(shí)更新且完整的 Rest API 文檔將會(huì)極大的提高我們的工作效率。傳統(tǒng)意義上的文檔都是后端開(kāi)發(fā)人員手動(dòng)編寫(xiě)的，相信大家也都知道這種方式很難保證文檔的及時(shí)性，這種文檔久而久之也就會(huì)失去其參考意義，反而還會(huì)加大我們的溝通成本。而 Swagger 給我們提供了一個(gè)全新的維護(hù) API 文檔的方式，下面我們就來(lái)了解一下它的優(yōu)點(diǎn)：

代碼變，文檔變。只需要少量的注解，Swagger 就可以根據(jù)代碼自動(dòng)生成 API 文檔，很好的保證了文檔的時(shí)效性。

跨語(yǔ)言性，支持 40 多種語(yǔ)言。

Swagger UI 呈現(xiàn)出來(lái)的是一份可交互式的 API 文檔，我們可以直接在文檔頁(yè)面嘗試 API 的調(diào)用，省去了準(zhǔn)備復(fù)雜的調(diào)用參數(shù)的過(guò)程。

還可以將文檔規(guī)范導(dǎo)入相關(guān)的工具（例如 SoapUI）, 這些工具將會(huì)為我們自動(dòng)地創(chuàng)建自動(dòng)化測(cè)試。

以上這些優(yōu)點(diǎn)足以說(shuō)明我們?yōu)槭裁匆褂?Swagger 了，您是否已經(jīng)對(duì) Swagger 產(chǎn)生了濃厚的興趣了呢？下面我們就將一步一步地在 Spring Boot 項(xiàng)目中集成和使用 Swagger，讓我們從準(zhǔn)備一個(gè) Spring Boot 的 Web 項(xiàng)目開(kāi)始吧。

SpringBoot整合Swagger2

1.首先創(chuàng)建一個(gè)基礎(chǔ)的SpringBoot web項(xiàng)目。您可以通過(guò) Spring Initializr 頁(yè)面生成一個(gè)空的 Spring Boot 項(xiàng)目，或者通過(guò)idea創(chuàng)建一個(gè)SpringBoot項(xiàng)目

2.添加依賴

Spring Boot 的 Web 依賴　

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId></dependency>

集成swagger2　

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version></dependency>

集成Swagger UI

<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version></dependency>

3.java中Swagger2配置-直接上配置代碼，Swagger2的配置是比較容易的，在成功項(xiàng)目創(chuàng)建之后，只需要開(kāi)發(fā)者自己提供一個(gè)Docket的Bean。（注釋寫(xiě)的很清楚，這里就不一一解釋了。不懂的地方可以在片尾關(guān)注我公眾號(hào)加我WX。）

/** * 集成swagger2 解決前后端分離 弊端：不能及時(shí)協(xié)商+今早解決的問(wèn)題 * 使用swagger總結(jié): * 通過(guò)swagger 給一些比基奧難理解的接口或?qū)傩裕黾幼⑨屝畔?* 接口文檔實(shí)時(shí)更新 * 可以在線測(cè)試 * 安全問(wèn)題: * 正式上線的時(shí)候 記得關(guān)閉swagger */@Configuration//加載到springboot配置里面@EnableSwagger2//開(kāi)啟swagger2public class SwaggerConfig { /** * 配置swagger2 * 注冊(cè)一個(gè)bean屬性 * swagger2其實(shí)就是重新寫(xiě)一個(gè)構(gòu)造器，因?yàn)樗麤](méi)有g(shù)et set方法 * enable() 是否啟用swagger false swagger不能再瀏覽器中訪問(wèn) * groupName()配置api文檔的分組 那就注冊(cè)多個(gè)Docket實(shí)例 相當(dāng)于多個(gè)分組 * @return */ @Bean public Docket docket() {​ return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).groupName('XXX')//組名稱.enable(true).select()/** * RequestHandlerSelectors配置掃描接口的方式 * basePackage 配置要掃描的包 * any 掃描全部 * none 不掃描 * withClassAnnotation 掃描類上的注解 * withMethodAnnotation 掃描方法上的注解 */.apis(RequestHandlerSelectors.basePackage('com.tinygray.madison.controller'))/** * paths() 掃描過(guò)濾方式 * any過(guò)濾全部 * none不過(guò)濾 * regex正則過(guò)濾 * ant過(guò)濾指定路徑 *///.paths(PathSelectors.ant('/login/**')).build(); }​ /** * 配置swagger2信息 =apiInfo * @return */ public ApiInfo apiInfo(){ /*作者信息*/// Contact contact = new Contact('XXX', 'http://baidu.com', 'email'); Contact contact = new Contact('', '', ''); return new ApiInfo('XXX的API接口','company接口','V1.0','urn:toVs',contact,'Apache 2.0','http://www.apache.org/licenses/LICENSE-2.0',new ArrayList()); }​}

4.編寫(xiě)一些簡(jiǎn)單的java接口。（你可以根據(jù)你的情況進(jìn)行編寫(xiě)）

@Api(tags = 'TestController測(cè)試')@RestControllerpublic class TestController { @ApiOperation('login api') @GetMapping('/') public String login() { return 'Hello login ~'; }​ @ApiOperation('helloWord Api') @GetMapping('/index') public String index() { return 'Hello World ~'; }​ @ApiOperation('admin Api') @GetMapping('/admin/hello') public String admin() { return 'hello admin!'; }​ @ApiOperation('user Api') @GetMapping('/user/hello') public String user() { return 'hello user'; }}

5.驗(yàn)證代碼-到這里我們已經(jīng)成功集成Swagger2，然后啟動(dòng)項(xiàng)目，輸入http://localhost:8080/swagger-ui.html，如果能出現(xiàn)下面界面，說(shuō)明配置成功了。

以上就是本文的全部?jī)?nèi)容，希望對(duì)大家的學(xué)習(xí)有所幫助，也希望大家多多支持好吧啦網(wǎng)。