Spring Boot給Java開發人員的生產力帶來極大的提高，尤其是構建RESTful API更是方便。使用RESTful服務通常是涉及到多個終端的團隊，比如Android、iOS、WEB等。為了讓大家溝通順暢，通常我們需要編寫一份詳細的RESTful業務接口文檔，文檔形式有Word或者Excel。但是我們也會發現有如下問題：

• 接口非常多，細節又復雜，如果由程序員高質量的輸出一個文檔，經常耗時長而且效果也不好，抱怨聲不絕與耳。
• 隨著時間的推移，文檔需要與代碼保持同步。但由于大部分程序員都還有著文檔不重要的思想，于是總有這樣那樣的原因導致程序員不愿意或遺忘了更新文檔。

我一直認為，代碼就是最好的文檔，如果能將代碼和注釋說明很好結合在一塊。既減輕了研發人員的負擔，又能輸出高質量的文檔，那就最好不過了。這一點Spring Boot也替我們想到了，那就是RESTful API的重磅好伙伴 Swagger2。
具體效果圖如下：

RESTful API Docs

下面我們以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

API測試

在上圖中我們可以看到book的Value是一個輸入框，下方還有一個"Try it out!"按鈕。沒錯，Swagger2還提供了接口測試功能，我們只要按照Book對象的Model Schema(黃色區域)示例進行參數修改，然后點擊"Try it out!"按鈕就可以進行接口測試了，大家也可以自行測試一下其他接口。

小結

相比編寫Word或Excel文檔而言，Swagger2雖然對代碼有一定的侵入性，但是我個人覺得還是可以接受的，畢竟減少了很多工作量，同時也增加了代碼的可讀性，非常值得推薦。
對比Swagger2，我還使用過apiDoc這個工具，使用感覺也不錯，大家有興趣也可以去試試看。

完整代碼戳這里: Chapter 3-1-3 - 利用Swagger2構建RESTful API文檔