Spring Boot 2.x基礎教程：使用Swagger2構建強大的API文件
隨著前後端分離架構和微服務架構的流行，我們使用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。具體效果如下圖所示：
下面來具體介紹，在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：許可證swagger.licenseUrl：許可證URLswagger.termsOfServiceUrl：服務條款URLswagger.contact.name：維護人swagger.contact.url：維護人URLswagger.contact.email：維護人emailswagger.base-package：swagger掃描的基礎包，預設：全掃描swagger.base-path：需要處理的基礎URL規則，預設：/**
更多配置說明可見官方說明：https://github.com/SpringForAll/spring-boot-starter-swagger
第四步：啟動應用，訪問：http://localhost:8080/swagger-ui.html，就可以看到如下的介面文件頁面：
新增文件內容
在整合完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目錄：
- Github：https://github.com/dyc87112/SpringBoot-Learning/tree/2.x
- Gitee：https://gitee.com/didispace/SpringBoot-Learning/tree/2.x
如果您覺得本文不錯，歡迎Star支援，您的關注是我堅持的動力！
歡迎關注我的公眾號：程式猿DD，獲得獨家整理的學習資源和日常乾貨推送。如果您對我的專題內容感興趣，也可以關注我的部落格：didispace.com