随着前後端分離架構和微服務架構的流行,我們使用Spring Boot來建構RESTful API項目的場景越來越多。通常我們的一個RESTful API就有可能要服務于多個不同的開發人員或開發團隊:IOS開發、Android開發、Web開發甚至其他的後端服務等。為了減少與其他團隊平時開發期間的頻繁溝通成本,傳統做法就是建立一份RESTful API文檔來記錄所有接口細節,然而這樣的做法有以下幾個問題:
- 由于接口衆多,并且細節複雜(需要考慮不同的HTTP請求類型、HTTP頭部資訊、HTTP請求内容等),高品質地建立這份文檔本身就是件非常吃力的事,下遊的抱怨聲不絕于耳。
- 随着時間推移,不斷修改接口實作的時候都必須同步修改接口文檔,而文檔與代碼又處于兩個不同的媒介,除非有嚴格的管理機制,不然很容易導緻不一緻現象。
為了解決上面這樣的問題,本文将介紹RESTful API的重磅好夥伴Swagger2,它可以輕松的整合到Spring Boot中,并與Spring MVC程式配合組織出強大RESTful API文檔。它既可以減少我們建立文檔的工作量,同時說明内容又整合入實作代碼中,讓維護文檔和修改代碼整合為一體,可以讓我們在修改代碼邏輯的同時友善的修改文檔說明。另外Swagger2也提供了強大的頁面測試功能來調試每個RESTful API。具體效果如下圖所示:
![](https://img.laitimes.com/img/__Qf2AjLwojIjJCLyojI0JCLiMVaX1EWvFnS4FXNNJ1a65UN0pGN0sGaGdDcyZ0Lc12bj5SZjFGczlGZpRmLn1Wavw1LcpDc0RHaiojIsJye.jpg)
下面來具體介紹,在Spring Boot中使用我們自己實作的starter來整合Swagger。該整合項目的Github:
https://github.com/SpringForAll/spring-boot-starter-swagger。如果您覺得它好用,歡迎Star支援我們!
準備工作
首先,我們需要一個Spring Boot實作的RESTful API工程,若您沒有做過這類内容,建議先閱讀上一篇教程:
Spring Boot 2.x基礎教程:建構RESTful API與單元測試建構一個。或者也可以直接使用上一篇教程中的樣例作為基礎,即下面倉庫中的
chapter2-1
工程:
- Github: https://github.com/dyc87112/SpringBoot-Learning/tree/2.x
- Gitee: https://gitee.com/didispace/SpringBoot-Learning/tree/2.x
整合Swagger2
下面,我們以上面倉庫中的
chapter2-1
工程進行整合改造。
第一步:添加swagger-spring-boot-starter依賴
在
pom.xml
中加入依賴,具體如下:
<dependency>
<groupId>com.spring4all</groupId>
<artifactId>swagger-spring-boot-starter</artifactId>
<version>1.9.0.RELEASE</version>
</dependency>
第二步:應用主類中添加
@EnableSwagger2Doc
注解,具體如下
@EnableSwagger2Doc
@SpringBootApplication
public class Chapter22Application {
public static void main(String[] args) {
SpringApplication.run(Chapter22Application.class, args);
}
}
第三步:
application.properties
中配置文檔相關内容,比如
swagger.title=spring-boot-starter-swagger
swagger.description=Starter for swagger 2.x
swagger.version=1.4.0.RELEASE
swagger.license=Apache License, Version 2.0
swagger.licenseUrl=https://www.apache.org/licenses/LICENSE-2.0.html
swagger.termsOfServiceUrl=https://github.com/dyc87112/spring-boot-starter-swagger
swagger.contact.name=didi
swagger.contact.url=http://blog.didispace.com
[email protected]
swagger.base-package=com.didispace
swagger.base-path=/**
各參數配置含義如下:
-
:标題swagger.title
-
:描述swagger.description
-
:版本swagger.version
-
:許可證swagger.license
-
:許可證URLswagger.licenseUrl
-
:服務條款URLswagger.termsOfServiceUrl
-
:維護人swagger.contact.name
-
:維護人URLswagger.contact.url
-
:維護人emailswagger.contact.email
-
:swagger掃描的基礎包,預設:全掃描swagger.base-package
-
:需要處理的基礎URL規則,預設:/**swagger.base-path
更多配置說明可見官方說明:
第四步:啟動應用,通路:
http://localhost:8080/swagger-ui.html
,就可以看到如下的接口文檔頁面:
![](https://img.laitimes.com/img/__Qf2AjLwojIjJCLyojI0JCLiMVaX1EWvFnS4FXNNJ1a65UN0pGN0sGaGdDcyZ0Lc12bj5SZjFGczlGZpRmLn1Wavw1LcpDc0RHaiojIsJye.jpg)
添加文檔内容
在整合完Swagger之後,在
http://localhost:8080/swagger-ui.html
頁面中可以看到,關于各個接口的描述還都是英文或遵循代碼定義的名稱産生的。這些内容對使用者并不友好,是以我們需要自己增加一些說明來豐富文檔内容。如下所示,我們通過
@Api
,
@ApiOperation
注解來給API增加說明、通過
@ApiImplicitParam
、
@ApiModel
@ApiModelProperty
注解來給參數增加說明。
比如下面的例子:
@Api(tags = "使用者管理")
@RestController
@RequestMapping(value = "/users") // 通過這裡配置使下面的映射都在/users下
public class UserController {
// 建立線程安全的Map,模拟users資訊的存儲
static Map<Long, User> users = Collections.synchronizedMap(new HashMap<>());
@GetMapping("/")
@ApiOperation(value = "擷取使用者清單")
public List<User> getUserList() {
List<User> r = new ArrayList<>(users.values());
return r;
}
@PostMapping("/")
@ApiOperation(value = "建立使用者", notes = "根據User對象建立使用者")
public String postUser(@RequestBody User user) {
users.put(user.getId(), user);
return "success";
}
@GetMapping("/{id}")
@ApiOperation(value = "擷取使用者詳細資訊", notes = "根據url的id來擷取使用者詳細資訊")
public User getUser(@PathVariable Long id) {
return users.get(id);
}
@PutMapping("/{id}")
@ApiImplicitParam(paramType = "path", dataType = "Long", name = "id", value = "使用者編号", required = true, example = "1")
@ApiOperation(value = "更新使用者詳細資訊", notes = "根據url的id來指定更新對象,并根據傳過來的user資訊來更新使用者詳細資訊")
public String putUser(@PathVariable Long id, @RequestBody User user) {
User u = users.get(id);
u.setName(user.getName());
u.setAge(user.getAge());
users.put(id, u);
return "success";
}
@DeleteMapping("/{id}")
@ApiOperation(value = "删除使用者", notes = "根據url的id來指定删除對象")
public String deleteUser(@PathVariable Long id) {
users.remove(id);
return "success";
}
}
@Data
@ApiModel(description="使用者實體")
public class User {
@ApiModelProperty("使用者編号")
private Long id;
@ApiModelProperty("使用者姓名")
private String name;
@ApiModelProperty("使用者年齡")
private Integer age;
}
完成上述代碼添加後,啟動Spring Boot程式,通路:
http://localhost:8080/swagger-ui.html
,就能看到下面這樣帶中文說明的文檔了(其中标出了各個注解與文檔元素的對應關系以供參考):
API文檔通路與調試
在上圖請求的頁面中,我們看到user的Value是個輸入框?是的,Swagger除了檢視接口功能外,還提供了調試測試功能,我們可以點選上圖中右側的Model Schema(黃色區域:它指明了User的資料結構),此時Value中就有了user對象的模闆,我們隻需要稍适修改,點選下方
“Try it out!”
按鈕,即可完成了一次請求調用!
此時,你也可以通過幾個GET請求來驗證之前的POST請求是否正确。
相比為這些接口編寫文檔的工作,我們增加的配置内容是非常少而且精簡的,對于原有代碼的侵入也在忍受範圍之内。是以,在建構RESTful API的同時,加入Swagger來對API文檔進行管理,是個不錯的選擇。
代碼示例
本文的完整工程可以檢視下面倉庫中的
chapter2-2
目錄:
如果您覺得本文不錯,歡迎
Star
支援,您的關注是我堅持的動力!
本文為「程式猿DD」原創,首發于: didispace.com 。 歡迎關注我的公衆号:程式猿DD,獲得獨家整理的學習資源和日常幹貨推送。