前言
Spring Boot 框架是目前非常流行的微服務框架，我們很多情況下使用它來提供 Rest API戒良。而對于 Rest API 來說很重要的一部分內容就是文檔体捏，Swagger 為我們提供了一套通過代碼和注解自動生成文檔的方法，這一點對于保證 API 文檔的及時性將有很大的幫助糯崎。本文將使用 Swagger 2 規(guī)范的 Springfox 實現(xiàn)來了解如何在 Spring Boot 項目中使用 Swagger几缭，主要包含了如何使用 Swagger 自動生成文檔、使用 Swagger 文檔以及 Swagger 相關的一些高級配置和注解沃呢。
Swagger 簡介
Swagger 是一套基于 OpenAPI 規(guī)范構建的開源工具年栓，可以幫助我們設計、構建薄霜、記錄以及使用 Rest API某抓。Swagger 主要包含了以下三個部分：
- Swagger Editor：基于瀏覽器的編輯器，我們可以使用它編寫我們 OpenAPI 規(guī)范惰瓜。
- Swagger UI：它會將我們編寫的 OpenAPI 規(guī)范呈現(xiàn)為交互式的 API 文檔否副，后文我將使用瀏覽器來查看并且操作我們的 Rest API。
- Swagger Codegen：它可以通過為 OpenAPI（以前稱為 Swagger）規(guī)范定義的任何 API 生成服務器存根和客戶端 SDK 來簡化構建過程崎坊。
為什么要使用 Swagger
當下很多公司都采取前后端分離的開發(fā)模式备禀，前端和后端的工作由不同的工程師完成。在這種開發(fā)模式下，維持一份及時更新且完整的 Rest API 文檔將會極大的提高我們的工作效率曲尸。傳統(tǒng)意義上的文檔都是后端開發(fā)人員手動編寫的赋续，相信大家也都知道這種方式很難保證文檔的及時性，這種文檔久而久之也就會失去其參考意義另患，反而還會加大我們的溝通成本纽乱。而 Swagger 給我們提供了一個全新的維護 API 文檔的方式，下面我們就來了解一下它的優(yōu)點：
- 代碼變柴淘，文檔變迫淹。只需要少量的注解秘通，Swagger 就可以根據代碼自動生成 API 文檔为严，很好的保證了文檔的時效性。
- 跨語言性肺稀，支持 40 多種語言第股。
- Swagger UI 呈現(xiàn)出來的是一份可交互式的 API 文檔，我們可以直接在文檔頁面嘗試 API 的調用话原，省去了準備復雜的調用參數的過程夕吻。
- 還可以將文檔規(guī)范導入相關的工具（例如 SoapUI）, 這些工具將會為我們自動地創(chuàng)建自動化測試。
以上這些優(yōu)點足以說明我們?yōu)槭裁匆褂?Swagger 了繁仁，您是否已經對 Swagger 產生了濃厚的興趣了呢涉馅？下面我們就將一步一步地在 Spring Boot 項目中集成和使用 Swagger，讓我們從準備一個 Spring Boot 的 Web 項目開始吧黄虱。
SpringBoot整合Swagger2
- 首先創(chuàng)建一個基礎的SpringBoot web項目稚矿。您可以通過 Spring Initializr 頁面生成一個空的 Spring Boot 項目，或者通過idea創(chuàng)建一個SpringBoot項目
- 添加依賴
1. Spring Boot的Web依賴
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
2. 集成swagger2
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
3. 集成Swagger UI
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
- java中Swagger2配置-直接上配置代碼捻浦，Swagger2的配置是比較容易的晤揣，在成功項目創(chuàng)建之后，只需要開發(fā)者自己提供一個Docket的Bean.（注釋寫的很清楚朱灿，這里就不一一解釋了昧识。不懂的地方可以在片尾關注我公眾號加我WX。）
/**
* 集成swagger2 解決前后端分離 弊端：不能及`在這里插入代碼片`時協(xié)商+今早解決的問題
* 使用swagger總結:
* 通過swagger 給一些比基奧難理解的接口或屬性盗扒，增加注釋信息
* 接口文檔實時更新
* 可以在線測試
* 安全問題:
* 正式上線的時候 記得關閉swagger
*/
@Configuration//加載到springboot配置里面
@EnableSwagger2//開啟swagger2
public class SwaggerConfig {
/**
* 配置swagger2
* 注冊一個bean屬性
* swagger2其實就是重新寫一個構造器跪楞，因為他沒有get set方法\
* enable() 是否啟用swagger false swagger不能再瀏覽器中訪問
* groupName()配置api文檔的分組 那就注冊多個Docket實例 相當于多個分組
* @return
*/
@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("qlh")//組名稱
.enable(true)
.select()
/**
* RequestHandlerSelectors配置掃描接口的方式
* basePackage 配置要掃描的包
* any 掃描全部
* none 不掃描
* withClassAnnotation 掃描類上的注解
* withMethodAnnotation 掃描方法上的注解
*/
.apis(RequestHandlerSelectors.basePackage("com.tinygray.madison.controller"))
/**
* paths() 掃描過濾方式
* any過濾全部
* none不過濾
* regex正則過濾
* ant過濾指定路徑
*/
// .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());
}
}
- 編寫一些簡單的java接口。（你可以根據你的情況進行編寫）
@Api(tags = "TestController測試")
@RestController
public 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";
}
}
- 驗證代碼-到這里我們已經成功集成Swagger2侣灶，然后啟動項目甸祭，輸入http://localhost:8080/swagger-ui.html，如果能出現(xiàn)下面界面炫隶，說明配置成功了淋叶。
img - 未完待續(xù)。下章節(jié)講解SpringBoot中優(yōu)雅的使用Swagger2【注解篇】-【2/2】
