SpringBoot的整合（四、整合Swagger2）

想必大家也搜索過Swagger的具體作用，這里不做過多闡述，簡單總結一下，Swagger就是用來幫助我們整理接口信息的，我們通過Swagger提供的注解，來對接口和model進行描述。

 

下面直接上干貨，springboot整合Swagger2。

（1）搭建一個springboot框架項目

首先，我們需要搭建好一個springboot的框架，如果不會搭建，可以參考我的一篇框架搭建入門文章，里面有詳細的代碼，希望可以幫助到大家：SpringBoot的整合（三、整合mybatis）

（2）修改pom.xml文件中

之后我們在pom.xml中添加Swagger相關的依賴

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

（3）寫一個配置類

之后需要我們提供一個配置類，首先通過@EnableSwagger2注解啟用Swagger2，然后配置一個Docket Bean，這個Bean中，配置映射路徑和要掃描的接口的位置，在apiInfo中，主要配置一下Swagger2文檔網站的信息，例如網站的title，網站的描述，聯系人的信息，使用的協議等等。這樣，Swagger2就算是配置成功了。要注意修改里面的掃描包的位置。位置隨意。

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

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.flyinghome.tm"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("SpringBoot整合Swagger測試")
                        .description("SpringBoot整合Swagger，詳細信息......")
                        .version("9.0")
                        .contact(new Contact("啊啊啊啊","blog.csdn.net","[e-mail]"))
                        .license("The Apache License")
                        .licenseUrl("http://www.baidu.com")
                        .build());
    }
}

我的這里是隨便建了一個config文件夾放入配置類

（4）啟動項目

最后啟動項目，瀏覽器中輸入：http://localhost:8080/swagger-ui.html，能夠看到如下頁面說明成功了。

（5）添加Swagger相關注解

此時我們開始添加注解：

首先在類上添加Api注解，方法上添加ApiOperation注解來對類和方法進行描述

@RestController
@RequestMapping(value = "/test")
@Api(tags = "用戶crud測試")
public class UserController {

    @Autowired
    private UserService userService;

    /**
     * Swagger測試
     */
    @PostMapping("/testSwagger")
    @ApiOperation("Swagger的測試")
    public User getUserByid(String name,String password){
        User user = new User();
        user.setName(name);
        user.setPassword(password);
        return user;
    }
    
}

在model類中使用@ApiModelProperty注解來描述各個屬性

package com.flyinghome.tm.model;

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

@Data
public class User {
    @ApiModelProperty(value = "用戶id")
    private String id;
    @ApiModelProperty(value = "用戶姓名")
    private String name;
    @ApiModelProperty(value = "用戶密碼")
    private String password;
    @ApiModelProperty(value = "頁碼")
    private String pageno;
    @ApiModelProperty(value = "數量")
    private String pagesize;
}

此時重新啟動瀏覽器刷新項目，可以看到頁面有了變化。即我們剛才填寫的備注都顯示在了對應的位置上。

（6）使用Swagger調試代碼

步驟5的圖中我們可以看到，在controller類中，我們有很多的接口，每個接口前面的圖標即是請求的類型，可以看出圖里的類中，有一個post請求和n個get請求，我們可以點擊對應的接口，輸入參數，進行調試。具體步驟如下：

 

（7）補充Swagger注解

Swagger的注解不僅僅是我上面所寫的那些，還有一部分，下面我總結一些常用的Swagger注解，大家用來參考：

1. @Api注解可以用來標記當前Controller的功能。

2. @ApiOperation注解用來標記一個方法的作用。

3. @ApiImplicitParam注解用來描述一個參數，可以配置參數的中文含義，也可以給參數設置默認值，這樣在接口測試的時候可以避免手動輸入。

4. 如果有多個參數，則需要使用多個@ApiImplicitParam注解來描述，多個@ApiImplicitParam注解需要放在一個@ApiImplicitParams注解中。

5. 需要注意的是，@ApiImplicitParam注解中雖然可以指定參數是必填的，但是卻不能代替@RequestParam(required = true)，前者的必填只是在Swagger2框架內必填，拋棄了Swagger2，這個限制就沒用了，所以假如開發者需要指定一個參數必填，@RequestParam(required = true)注解還是不能省略。

6. 如果參數是一個對象（例如上文的更新接口），對於參數的描述也可以放在實體類中。

 

參考：

1. https://blog.csdn.net/u012702547/article/details/88775298

2. https://blog.csdn.net/miachen520/article/details/95722887

持續更新！！！