由於Spring Boot能夠快速開發、便捷部署等特性，相信有很大一部分Spring Boot的使用者會用來構建RESTful API。而我們構建RESTful API的目的通常都是由於多終端的原因，這些終端會共用很多底層業務邏輯，因此我們會抽象出這樣一層來同時服務於多個移動端或者Web前端。本文將介紹RESTful API的重磅好夥伴Swagger2，它可以輕鬆的整合到Spring Boot中，並與Spring MVC程式配合組織出強大RESTful API文件。它既可以減少我們建立文件的工作量，同時說明內容又整合入實現程式碼中，讓維護文件和修改程式碼整合為一體，可以讓我們在修改程式碼邏輯的同時方便的修改文件說明。另外Swagger2

也提供了強大的頁面測試功能來除錯每個RESTful API。此引用來自程式猿DD。

在Spring Boot中應用中Swagger2構建強大的API文件十分方便，只需要在專案中新增Swagger2的依賴，然後在Spring Boot的啟動的main方法的類上加上註解@EnableSwagger2就可以完成構建工作。效果圖如下：

在圖中可以看出，我自定義的Controller只有FileController，而其他的都是Spring Boot的一些控制器，而這些API文件往往是我們不需要的，所以，僅僅使用Swagger2的預設方式顯然是不能滿足我們的需求的，所以，我們需要自定義Swagger

新增依賴

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId
 
>
    <version>2.8.0</version>
</dependency>

配置Swagger

我們寫一個Swagger的配置類，新增上@Configuration註解方便被Spring Boot配置，新增@EnableSwagger2註解啟動Swagger文件構建能力。需要注意的是，一般配置類可以放在Spring Boot啟動類的同一個包裡，如果沒有放，那麼請在Spring Boot的啟動類上新增包掃描註解@ComponentScan(basePackages = {"com.lemon.security"})，然後配置類可以放在任何的這個包的子包下面。

package com.lemon.security.web.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author lemon
 * @date 2018/4/3 下午1:01
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestfulApiDocs() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lemon.security.web.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("自定義RESTful API文件")
                .description("更多內容請關注CSDN部落格：https://blog.csdn.net/Lammonpeter")
                .termsOfServiceUrl("https://blog.csdn.net/Lammonpeter")
                .contact(new Contact("Lemon", "https://blog.csdn.net/Lammonpeter", "[email protected]"))
                .version("1.0.0")
                .build();
    }
}

對上面的程式碼有如下解釋：
通過createRestfulApiDocs方法建立Docket的Bean之後，apiInfo()用來建立該API的基本資訊（這些基本資訊會展現在文件頁面中）。select()函式返回一個ApiSelectorBuilder例項用來控制哪些介面暴露給Swagger來展現，本例採用指定掃描的包路徑來定義，Swagger會掃描該包下所有Controller定義的API，併產生文件內容（除了被@ApiIgnore指定的請求）。

新增文件內容

在完成了上述配置後，其實已經可以生產文件內容，但是這樣的文件主要針對請求本身，而描述主要來源於函式等命名產生，對使用者並不友好，我們通常需要自己增加一些說明來豐富文件內容。如下所示，我們通過@ApiOperation註解來給API方法增加說明，通過@ApiImplicitParams、@ApiImplicitParam註解來給引數增加說明，通過@ApiModelProperty註解來給實體類的屬性增加說明。

• 給Controller新增文件說明：

package com.lemon.security.web.controller;

import cn.hutool.core.io.IoUtil;
import com.lemon.security.web.dto.FileInfo;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.*;

/**
 * @author lemon
 * @date 2018/4/2 下午2:19
 */
@RestController
@RequestMapping("/file")
public class FileController {

    private static String folder = "/Users/lemon/IdeaProjects/spring-security/lemon-security-demo";

    @PostMapping
    @ApiOperation(value = "檔案上傳介面", notes = "訪問此介面可以實現檔案上傳")
    @ApiImplicitParam(name = "file", value = "使用MultipartFile的例項物件來接收檔案資料", required = true, dataTypeClass = MultipartFile.class)
    public FileInfo upload(@RequestParam("file") MultipartFile file) throws IOException {
        System.out.println("上傳檔案的表單name值為：" + file.getName());
        System.out.println("檔案路徑為：" + file.getOriginalFilename());
        System.out.println("檔案大小為：" + file.getSize());
        File localFile = new File(folder, System.currentTimeMillis() + ".txt");
        // 執行上傳操作
        file.transferTo(localFile);
        return new FileInfo(localFile.getAbsolutePath());
    }

    @GetMapping("/{id}")
    @ApiOperation(value = "檔案下載介面", notes = "訪問此介面並提供檔案ID即可下載檔案")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "檔案ID", required = true, dataTypeClass = String.class),
            @ApiImplicitParam(name = "request", value = "HttpServletRequest例項物件，自動注入，無需傳遞", required = true, dataTypeClass = HttpServletRequest.class),
            @ApiImplicitParam(name = "response", value = "HttpServletResponse例項物件，自動注入，無需傳遞", required = true, dataTypeClass = HttpServletResponse.class)
    })
    public void download(@PathVariable String id, HttpServletRequest request, HttpServletResponse response) {
        System.out.println(folder);
        try (
                // 這是JDK7的特性，關於流的操作，可以寫在try後面的圓括號裡，這樣就無需手動關閉流
                InputStream inputStream = new FileInputStream(new File(folder, id + ".txt"));
                OutputStream outputStream = response.getOutputStream()
        ) {
            // 設定下載的檔案型別
            response.setContentType("application/x-download");
            // 設定下載後的檔名
            response.setHeader("Content-Disposition", "attachment;filename=test.txt");
            IoUtil.copy(inputStream, outputStream);
            // 重新整理輸出流
            outputStream.flush();
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

其中，
@ApiOperation註解的value屬性一般都是簡單描述API的功能，notes屬性詳細描述API的功能；
@ApiImplicitParams用來描述一個方法的多個引數的註解；
@ApiImplicitParam用來表述單個引數，name屬性來描述引數的名稱，value用來描述引數的意思，required表示引數是否是必需值，dataTypeClass或者dataType指定了資料的型別。
這裡僅僅是對註解進行說明，而程式碼本身來自上一節內容，即《Spring Security技術棧開發企業級認證與授權（六）使用REST方式處理檔案服務》。

• 給實體類新增文件說明：

package com.lemon.security.web.dto;

import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * @author lemon
 * @date 2018/4/2 下午2:24
 */
@Data
public class FileInfo {

    @ApiModelProperty(value = "檔案上傳後的檔案路徑")
    private String path;

    public FileInfo(String path) {
        this.path = path;
    }
}

其中，@ApiModelProperty用來描述引數的意義。

配置完成以後，執行Spring Boot應用，在位址列訪問http://localhost:8080/swagger-ui.html就可以進入自定義的Swagger文件介面，效果圖如下：

API文件訪問與除錯

在上圖請求的頁面中，Swagger除了檢視介面功能外，還提供了除錯測試功能，點選“Try it out！”按鈕，即可完成了一次請求呼叫！此時，你也可以通過幾個POST請求來驗證之前的POST請求是否正確。相比為這些介面編寫文件的工作，我們增加的配置內容是非常少而且精簡的，對於原有程式碼的侵入也在忍受範圍之內。因此，在構建RESTful API的同時，加入Swagger來對API文件進行管理，是個不錯的選擇。

Spring Security技術棧開發企業級認證與授權系列文章列表：

示例程式碼下載地址：

專案已經上傳到碼雲，歡迎下載，內容所在資料夾為chapter007。