一篇文章帶你搞定 SpringBoot 整合 Swagger2

一、建立工程

建立 SpringBoot 工程專案，建立時只需要加入  spring-boot-starter-web 依賴即可，
Maven 倉庫搜尋 Swagger2 依賴：

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

<!-- artifact/io.springfox/springfox-swagger-ui --><dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version></dependency>1234567

二、Swagger2 配置

Swagger2的配置也是比較容易的，在專案建立成功之後，只需要開發者自己提供一個Docket的Bean即可，如下：

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.Contact;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2WebFlux;@Configuration@EnableSwagger2public class Swagger2Config {
    @Bean
    Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.yolo.swagger2.controller"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        //網站描述
                        .description("介面文件的描述資訊")
                        .title("微人事專案介面文件")
                        //聯絡人資訊
                        .contact(new Contact("yolo","blog.csdn.net","xxxx@gmail.com"))
                        //版本
                        .version("v1.0")
                        .license("Apache2.0")
                        .build());
    }}12345678910111213141516171819202122232425262728293031

這裡提供一個配置類，首先透過 @EnableSwagger2WebFlux註解啟用 Swagger2，然後配置一個Docket Bean，這個Bean中，配置對映路徑和要掃描的介面的位置，在apiInfo中，主要配置一下Swagger2文件網站的資訊，例如網站的title，網站的描述，聯絡人的資訊，使用的協議等等。

三、簡單示例

（1）定義 User

public class User {
    private Integer id;
    private String username;
    private String address;
    //get,set 方法省略}123456

（2）定義 Controller    

@RestControllerpublic class UserController {
    @GetMapping("/user")
    public User getUserById(Integer id){
        User user = new User();
        user.setId(id);
        return user;
    }}123456789

在這種 restful 風格的程式碼裡，需要明確指定介面是什麼請求（get/post 等），不能直接寫成  requestMapping，不然前端會生成6個方法，get，post 等都能發，會比較混亂。

啟動專案，訪問：

也可以配置成中文描述

四、中文配置案例

（1）對於引數的描述可以放在實體類中

@ApiModel(value = "使用者實體類",description = "使用者資訊描述類")public class User {
    @ApiModelProperty(value = "使用者id")
    private Integer id;
    @ApiModelProperty(value = "使用者名稱")
    private String username;
    @ApiModelProperty(value = "使用者地址")
    private String address;
	//get,set 方法省略}12345678910

（2）建立介面

@RestController@Api(tags = "使用者資料介面")public class UserController {
    @ApiOperation(value = "查詢使用者", notes = "根據使用者id查詢使用者")
    @ApiImplicitParam(name = "id", value = "使用者id", required = true, defaultValue = "99")
    @GetMapping("/user")
    public User getUserById(Integer id) {
        User user = new User();
        user.setId(id);
        return user;
    }
    @ApiOperation(value = "刪除使用者", notes = "根據使用者id刪除使用者")
    @ApiImplicitParam(name = "id", value = "使用者id", required = true, defaultValue = "99")
    @ApiResponses({
            @ApiResponse(code = 200, message = "刪除成功"),
            @ApiResponse(code = 500, message = "刪除失敗")
    })
    @DeleteMapping("/user/{id}")
    public void deleteUserById(@PathVariable Integer id) {
        System.out.println("deleteUserById:" + id);
    }
    @PutMapping("/user")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "使用者id", required = true, defaultValue = "99"),
            @ApiImplicitParam(name = "username", value = "使用者名稱", required = true, defaultValue = "javaboy")
    })
    @ApiOperation(value = "更新使用者", notes = "根據使用者id更新使用者名稱")//    @ApiIgnore
    public User updateUsernameById(String username, Integer id) {
        User user = new User();
        user.setId(id);
        user.setUsername(username);
        return user;
    }
    @PostMapping("/user")
    @ApiOperation(value = "新增使用者", notes = "新增使用者介面")
    public User addUser(@RequestBody User user) {
        return user;
    }}12345678910111213141516171819202122232425262728293031323334353637383940414243

（1） @Api註解可以用來標記當前 Controller的功能。
（2） @ApiOperation註解用來標記一個方法的作用。
（3） @ApiImplicitParam註解用來描述一個引數，可以配置引數的中文含義，也可以給引數設定預設值，這樣在介面測試的時候可以避免手動輸入。
（4）如果有多個引數，則需要使用多個 @ApiImplicitParam註解來描述，多個 @ApiImplicitParam註解需要放在一個 @ApiImplicitParams註解中。
（5）需要注意的是， @ApiImplicitParam註解中雖然可以指定引數是必填的，但是卻不能代替 @RequestParam(required = true)，前者的必填只是在Swagger2框架內必填，拋棄了Swagger2，這個限制就沒用了，所以假如開發者需要指定一個引數必填， @RequestParam(required = true)註解還是不能省略。

（3）效果展示 /henan/

可以看到，所有的介面這裡都列出來了，包括介面請求方式，介面地址以及介面的名字等，點開一個介面，可以看到如下資訊： jiyuan/

可以看到，介面的引數，引數要求，引數預設值等等統統都展示出來了，引數型別下的 query表示引數以 key/value的形式傳遞，點選右上角的 Try it out，就可以進行介面測試：

點選Execute按鈕，表示傳送請求進行測試。測試結果會展示在下面的Response中。

小夥伴們注意，引數型別下面的 query表示引數以 key/value的形式傳遞，這裡的值也可能是 body， body表示引數以請求體的方式傳遞，例如上文的更新介面，如下： /question/

當然還有一種可能就是這裡的引數為path，表示引數放在路徑中傳遞，例如根據id查詢使用者的介面：

五、在 Security 中的配置

如果我們的Spring Boot專案中整合了Spring Security，那麼如果不做額外配置，Swagger2文件可能會被攔截，此時只需要在Spring Security的配置類中重寫configure方法，新增如下過濾即可：

@Overridepublic void configure(WebSecurity web) throws Exception {
    web.ignoring()
            .antMatchers("/swagger-ui.html")
            .antMatchers("/v2/**")
            .antMatchers("/swagger-resources/**");}1234567

如此之後，Swagger2檔案就不需要認證就能訪問了。