使用Swagger2構建Spring Boot RESTful AIP 文檔

    上一篇咱們介紹瞭如何使用Spring Boot快速構建RESTful API 「Spring Boot與RESTful API 」 ，本篇則介紹一個配合Spring Boot快速構建RESTful文檔的工具

    因爲Spring Boot具備快速開發、便捷部署的特色，不少用戶會使用Spring Boot構建RESTful API，一個RESTful接口每每對應不止一個終端，有WEB端、安卓端、IOS端等等。正由於這樣，一個接口可能要面對多個開發人員或者團隊，爲了減小溝通來帶的時間成本，你們每每會準備一個RESTful API的文檔，可是這種文檔每每有幾個致命的問題：

1. 因爲接口過多，細節複雜，文檔自己構建起來就比較麻煩
2. 隨着時間的推移，接口每每會修改或者廢棄，這就須要對全部調用方同步文檔，若是出現遺漏，很容易形成接口調用失敗

    爲了解決以上問題，就要介紹一下Swagger2，它能夠很簡單的整合到Spring Boot中，它能夠組織出強大的RESTful API文檔。效果如圖：

    這次以上篇文章的代碼爲例對Swagger2進行講解。

導入Swagger2依賴

    在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類

    Swagger2類須要與Application.java同級

@Configuration
@EnableSwagger2
public class Swagger2 {
    @Bean
    public Docket createRestApi() {
        //須要配置正確須要掃面的的包名
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wangxin.restapi"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構建RESTful APIs")
                .description("更多Spring Boot相關文章請關注：https://my.oschina.net/wangxincj/blog/")
                .termsOfServiceUrl("https://my.oschina.net/wangxincj/blog/")
                .contact("老虎是個蛋蛋")
                .version("1.0")
                .build();
    }
}

    如上所示，

• 添加@Configuration註解，表示讓Spring在啓動時加載該配置
• @EnableSwagger2表示在Spring Boot中啓動Swagger2
• createRestApi方法建立Docket的Bean
• apiInfo()用來建立該API的基本信息
• ApiInfoBuilder實力來控制那些接口須要暴露給Swagger來展示

添加文檔內容註解

    咱們經過使用@ApiOperation註解對接口進行描述，經過@ApiImplicitParam和@ApiImplicitParams對參數進行描述

@RestController
@RequestMapping("/book")
public class BookController {
    public static Map<String,Book> bookMap = new HashMap<String,Book>();

    /**
     * 添加一本書
     * @param book
     * @return
     */
    @ApiOperation(value="建立一本書", notes="建立一本書")
    @ApiImplicitParam(name = "book", value = "book實體bean", required = true, dataType = "Book")
    @RequestMapping(value="",method = RequestMethod.POST)
    public String postBook (@ModelAttribute Book book){
        bookMap.put(book.getIsbn(),book);
        return "SUCCESS";
    }

    /**
     * 查詢出全部book集合
     * @return
     */
    @ApiOperation(value="查詢出全部book集合", notes="")
    @RequestMapping(value={""},method = RequestMethod.GET)
    public List<Book> getBookList (){
        List<Book> bookList = new ArrayList<Book>(bookMap.values());
        return bookList;
    }

    /**
     * 根據ISBN獲取book
     * @param isbn
     * @return
     */
    @ApiOperation(value="圖書詳細信息", notes="根據url的isbn來獲取圖書詳細信息")
    @ApiImplicitParam(name = "isbn", value = "ISBN", required = true, dataType = "String")
    @RequestMapping(value="/{isbn}",method = RequestMethod.GET)
    public Book getBook(@PathVariable String isbn){
        Book book = bookMap.get(isbn);
        return book;
    }

    /**
     * 更新book參數
     * @param isbn
     * @param book
     * @return
     */
    @ApiOperation(value="更新圖書詳細信息", notes="根據url的ISBN來指定更新對象，並根據傳過來的book信息來更新圖書詳細信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "isbn", value = "ISBN", required = true, dataType = "String"),
            @ApiImplicitParam(name = "book", value = "圖書詳細實體book", required = true, dataType = "Book")
    })
    @RequestMapping(value="/{isbn}",method = RequestMethod.PUT)
    public String putBook(@PathVariable String isbn, @ModelAttribute Book book){
        Book b = bookMap.get(isbn);
        b.setAuthor(book.getAuthor());
        b.setName(book.getName());
        bookMap.put(isbn,b);
        return "SUCCESS";
    }

    /**
     * 根據isbn刪除book
     * @param isbn
     * @return
     */
    @ApiOperation(value="刪除圖書", notes="根據url的ISBN來指定刪除圖書")
    @ApiImplicitParam(name = "isbn", value = "ISBN", required = true, dataType = "String")
    @RequestMapping(value="/{isbn}",method = RequestMethod.DELETE)
    public String deleteBook(@PathVariable String isbn){
        bookMap.remove(isbn);
        return "SUCCESS";
    }
}

    完成以上操做，咱們啓動Spring Boot，訪問http://localhost:8080/swagger-ui.html，便可看到Swagger2生成的RESTful API，以下：

API調試

    Swagger2不只能夠生成API文檔，還能夠在線調試接口，如上圖，有兩種填寫參數方式，第一種是在Parameter列表項中有Book對象須要填寫的參數，你們能夠根據實際狀況填寫參數值；第二種方式咱們能夠點擊上圖中右側的Model Schema（黃色區域：它指明瞭Book的數據結構），此時Value中就有了book對象的模板，咱們只須要稍適修改。填寫完參數點擊「Try it out!」便可完成接口請求。

    相比爲這些接口編寫文檔的工做，咱們增長的配置內容是很是少並且精簡的，對於原有代碼的侵入也在忍受範圍以內。所以，在構建RESTful API的同時，加入swagger來對API文檔進行管理，是個不錯的選擇。

• swagger官網