Spring Boot給Java開發人員的生產力帶來極大的提高，尤其是構建RESTful API更是方便。使用RESTful服務通常是涉及到多個終端的團隊，比如Android、iOS、WEB等。為了讓大家溝通順暢，通常我們需要編寫一份詳細的RESTful業務接口文檔，文檔形式有Word或者Excel。但是我們也會發現有如下問題：
- 接口非常多，細節又復雜，如果由程序員高質量的輸出一個文檔，經常耗時長而且效果也不好，抱怨聲不絕與耳。
- 隨著時間的推移，文檔需要與代碼保持同步。但由于大部分程序員都還有著文檔不重要的思想，于是總有這樣那樣的原因導致程序員不愿意或遺忘了更新文檔。
我一直認為，代碼就是最好的文檔，如果能將代碼和注釋說明很好結合在一塊。既減輕了研發人員的負擔，又能輸出高質量的文檔，那就最好不過了。這一點Spring Boot也替我們想到了，那就是RESTful API的重磅好伙伴 Swagger2。
具體效果圖如下：
下面我們以Chapter 3-1-1: 構建一個復雜的RESTful API及單元測試中的代碼為例，看看如何將Swagger2集成到Spring Boot工程中創建一個RESTful API文檔
pom.xml中添加Swagger2依賴
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
創建Swagger2配置類
在RestApplication.java同級路徑下創建SwaggerConfig.java
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
ApiInfo apiInfo = new ApiInfoBuilder()
.title("使用Swagger2構建RESTful APIs")
.description("客戶端與服務端接口文檔")
.termsOfServiceUrl("http://localost:8080")
.contact("bluecoffee")
.version("1.0.0")
.build();
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo)
.select()
.apis(RequestHandlerSelectors.basePackage("com.bluecoffee.rest"))
.paths(PathSelectors.any())
.build();
}
}
上述代碼中，通過@Configuration注解，讓Spring來加載該類配置，通過@EnableSwagger2注解來啟用Swagger2。
再通過createRestApi函數創建Docket的Bean之后，apiInfo是用來創建接口文檔的基本信息（這些基本信息會展現在文檔頁面中）。select()函數返回一個ApiSelectorBuilder實例用來控制哪些接口暴露給Swagger來展現，本例采用指定掃描的包路徑來定義，Swagger會掃描該包下所有Controller定義的API，并產生文檔內容（除了被@ApiIgnore指定的請求）。
創建API接口描述信息
@RestController
@RequestMapping(value="/books")
public class BookController {
// 創建線程安全的Map
static Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long, Book>());
@ApiOperation(value="獲取書籍列表", notes="")
@RequestMapping(value={"/"}, method=RequestMethod.GET)
public List<Book> getBookList() {
// 處理"/books/"的GET請求，用來獲取圖書列表
// 還可以通過@RequestParam傳遞參數來進行查詢條件或者翻頁信息的傳遞
List<Book> r = new ArrayList<Book>(books.values());
return r;
}
@ApiOperation(value="創建書籍", notes="根據Book對象創建書籍")
@ApiImplicitParam(name = "book", value = "書籍實體對象Book", required = true, dataType = "Book")
@RequestMapping(value="/", method=RequestMethod.POST,produces = "application/json")
public JsonResult createBook(@RequestBody Book book) {
// 處理"/books/"的POST請求，用來創建User
// 除了@ModelAttribute綁定參數之外，還可以通過@RequestParam從頁面中傳遞參數
books.put(book.getBookId(), book);
JsonResult jr = new JsonResult();
jr.setIsSuccessful(true);
jr.setResultCode("0000");
jr.setResultDesc("success");
return jr;
}
@ApiOperation(value="獲取書籍詳細信息", notes="根據URL中的bookId來獲取書籍詳細信息")
@ApiImplicitParam(name = "bookId", value = "書籍ID", required = true, dataType = "Long")
@RequestMapping(value="/{bookId}", method=RequestMethod.GET)
public Book getBook(@PathVariable Long bookId) {
// 處理"/books/{id}"的GET請求，用來獲取url中id值的Book信息
// url中的id可通過@PathVariable綁定到函數的參數中
return books.get(bookId);
}
@ApiOperation(value="更新書籍信息", notes="根據URL中的bookId來指定更新書籍，并根據傳過來的Book信息來更新書籍詳細信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "bookId", value = "書籍ID", required = true, dataType = "Long"),
@ApiImplicitParam(name = "book", value = "書籍詳細實體book", required = true, dataType = "Book")
})
@RequestMapping(value="/{bookId}", method=RequestMethod.PUT)
public JsonResult putBook(@PathVariable Long bookId, @RequestBody Book book) {
// 處理"/books/{bookId}"的PUT請求，用來更新Book信息
Book b = books.get(bookId);
b.setTitle(book.getTitle());
b.setAuthor(book.getAuthor());
books.put(bookId, b);
JsonResult jr = new JsonResult();
jr.setIsSuccessful(true);
jr.setResultCode("0000");
jr.setResultDesc("success");
return jr;
}
@ApiOperation(value="刪除書籍", notes="根據URL中的bookId來指定刪除書籍")
@ApiImplicitParam(name = "bookId", value = "書籍ID", required = true, dataType = "Long")
@RequestMapping(value="/{bookId}", method=RequestMethod.DELETE)
public JsonResult deleteBook(@PathVariable Long bookId) {
// 處理"/books/{bookId}"的DELETE請求，用來刪除Book
books.remove(bookId);
JsonResult jr = new JsonResult();
jr.setIsSuccessful(true);
jr.setResultCode("0000");
jr.setResultDesc("success");
return jr;
}
}
我們通過@ApiOperation注解來給API增加說明、通過@ApiImplicitParams、@ApiImplicitParam注解來給參數增加說明。
完成這些工作后，我們再啟動Spring Boot程序，訪問：http://localhost:8080/swagger-ui.html。就能看到之前所展示的RESTful API的頁面。我們可以再點開具體的API請求，以POST類型的/books/為例：
API測試
在上圖中我們可以看到book的Value是一個輸入框，下方還有一個"Try it out!"按鈕。沒錯，Swagger2還提供了接口測試功能，我們只要按照Book對象的Model Schema(黃色區域)示例進行參數修改，然后點擊"Try it out!"按鈕就可以進行接口測試了，大家也可以自行測試一下其他接口。
小結
相比編寫Word或Excel文檔而言，Swagger2雖然對代碼有一定的侵入性，但是我個人覺得還是可以接受的，畢竟減少了很多工作量，同時也增加了代碼的可讀性，非常值得推薦。
對比Swagger2，我還使用過apiDoc這個工具，使用感覺也不錯，大家有興趣也可以去試試看。
