springboot 接入RESTful 風格的 Web 服務框架 Swagger 生成接口文檔

借鑑：https://www.jianshu.com/p/f4fb5e9899fc

前言：作爲一個以前後端分離爲模式開發小組，我們每隔一段時間都進行這樣一個場景：前端人員和後端開發在一起熱烈的討論"哎,你這參數又變了啊","接口怎麼又請求不通了啊","你再試試,我打個斷點調試一下.."。可以看到在前後端溝通中出現了不少問題。

對於這樣的問題,之前一直沒有很好的解決方案，直到它的出現，沒錯...這就是我們今天要討論的神器:swagger,一款致力於解決接口規範化、標準化、文檔化的開源庫，一款真正的開發神器。

一：swagger是什麼？

Swagger是一款RESTFUL接口的文檔在線自動生成+功能測試功能軟件。Swagger是一個規範和完整的框架,用於生成、描述、調用和可視化RESTful風格的Web服務。目標是使客戶端和文件系統作爲服務器以同樣的速度來更新文件的方法,參數和模型緊密集成到服務器。

這個解釋簡單點來講就是說，swagger是一款可以根據resutful風格生成的生成的接口開發文檔，並且支持做測試的一款中間軟件。

二：爲什麼要使用swaager?

2.1:對於後端開發人員來說

不用再手寫WiKi接口拼大量的參數，避免手寫錯誤

對代碼侵入性低，採用全註解的方式，開發簡單

方法參數名修改、增加、減少參數都可以直接生效，不用手動維護

缺點：增加了開發成本，寫接口還得再寫一套參數配置

2.2:對於前端開發來說

後端只需要定義好接口，會自動生成文檔，接口功能、參數一目瞭然

聯調方便，如果出問題，直接測試接口，實時檢查參數和返回值,就可以快速定位是前端還是後端的問題

2.3：對於測試

對於某些沒有前端界面UI的功能，可以用它來測試接口

操作簡單，不用瞭解具體代碼就可以操作

操作簡單，不用瞭解具體代碼就可以操作

配置信息

pom引入swagger依賴

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

配置文件：

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    private static final String BASE_PACKAGE = "com.xxx.xxx.xxx.xxx.controller";

    @Bean
    public Docket docket() {
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder().title("主數據字典維護 Restful API");

        return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors
                .basePackage(BASE_PACKAGE)).paths(PathSelectors.any()).build().apiInfo(apiInfoBuilder.build());
    }
}

接口配置

@RestController
public class TestController extends AbstractBasicController {

    @Autowired
    private TestService testService;


    @ApiOperation(response = RestDataResponse.class, value = "獲取數據")
    @GetMapping("/test")
    public RestDataResponse getTestInfo(Integer id) {
        return newRestDataResponse(testService.selectOne(id));
    }

}

默認的訪問地址：ip:port/swagger-ui.html#/

4.2:訪問本地鏈接

http://localhost:8080/swagger-ui.html#/

可以看出訪問的url都很清晰的展示在它最終的頁面上，我們打開一個方法：可以看出方法的請求參數清晰的的羅列出來，包括方法的返回值。並且有一個很重要的功能，只需要點下方的try it out就可以進行接口測試，

 

在GET請求中，參數在Body體裏面,不能使用@RequestBody。在POST請求，可以使用@RequestBody和@RequestParam，如果使用@RequestBody，對於參數轉化的配置必須統一

controller必須指定請求類型，否則swagger會把所有的類型(6種)都生成出來

swagger在生產環境不能對外暴露,可以使用@Profile({“dev”, “prod”,“pre”})指定可以使用的環境