超简单的springboot+swagger2实现在线接口调试

前言：

    作为标标准准的后台开发攻城狮，在于前端交互给其提供接口的时候，是不是要给其准备接口文档？是不是在和他联调之前首先要自测通过呢？是不是自测之前要写接口调用（比如postman）呢？作为一个负责滴、追求向上滴工程师，那这些肯定是要做的。事情都要做，可做事的方式不同，结果和效率也不同，那么下面和大家分享一下springboot项目中提供的接口如何方便快捷提供一种自测，甚至是直接给接口测试人员测试的方式，那就是整合进去seagger2.用了还想用的第三方插件吧，

申明：

    我不喜欢文章很复杂，追求简而美观的实用性，但是为了需要的伙伴能够直接一步到位，绝对可用，所以直接粘贴的核心代码，方便你们复制过去，因此给文章增加了看起来不太友好的复杂度。

开发环境：

1、添加依赖

这里默认我们已使用的maven项目，否则的话请自行下载依赖相关的java包也一样，项目引入以下依赖：

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2、添加配置类

package cn.seally.community.config;

import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import com.google.common.base.Predicate;

import springfox.documentation.builders.ApiInfoBuilder;
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;

/**
 * @Description swagger在线接口插件配置类
 * @Date 2019年8月31日
 * @author seallydeng
 */
@Configuration
@EnableSwagger2 //开启在线接口文档
public class SwaggerConfig {
 
    /**
     * @Description
     * @Date 2019年8月31日
     * @author seallydeng
     * @return
     */
    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("标题：Seally Web 接口文档")//标题
                        .description("本系统接口主要包括xxx、yyy等功能模块")//描述
                        .contact(new Contact("dningcheng", "http://www.xxx.com/web", "dningcheng@163.com"))
                        .version("1.0.0")//版本号
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("cn.seally.community.controller"))//配置扫描的控制器类包
                .paths(paths())//配置符合指定规则的路径接口才生成在线接口，用于定制那些接口在ui中展示
                .build();
    }
   
    @SuppressWarnings("unchecked")
   private Predicate<String> paths() {
        return or(regex("/user/api/.*?"));
    }
}

3、控制器以注解方式增加接口描述信息

package cn.seally.community.controller;

import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import cn.seally.community.common.ApiResponse;
import cn.seally.community.model.base.SystemUser;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

/**
 * @Description 用于演示swagger在线接口文档的控制器
 * @Date 2019年8月31日
 * @author seallydeng
 */
@Api(tags={"系统首页热点图相关接口"}) //标注在类上：用以备注接口组名称
@RestController
@RequestMapping("/demo")
public class DemoController {
 
 @ApiOperation(value="获取用户信息",notes="username是唯一属性，单个用户可直接通过username获取") //标注在方法：用以备注接口描述
 @GetMapping(value="/user/query")
 public ApiResponse<String> getUserInfo(String username){
  return ApiResponse.success("获取信息通过");
 }
 
 @PostMapping(value="/user/save",produces="application/json")
 public ApiResponse<String> saveUserInfo(@RequestBody SystemUser user){
  return ApiResponse.success("保存用户信息成功");
 }
 
 @PutMapping(value="/user/update",produces="application/json")
 public ApiResponse<String> updateUserInfo(@RequestBody SystemUser user){
  return ApiResponse.success("修改用户信息成功");
 }
 
 @DeleteMapping(value="/user/delete/{username}",produces="application/json")
 public ApiResponse<String> deleteUserInfo(@PathVariable("username") String username){
  return ApiResponse.success("删除用户信息成功");
 }
}

4、启动项目，进行访问

    在浏览器输入访问路径即可访问，通常如果项目没有配置路径则直接使用：http://ip:port/swagger-ui.html 即可访问，如果springboot配置了项目路径如:

那么访问的路径名则为：http://ip:port/seally-community-web/swagger-ui.html 

如果项目正常，则可看到如下界面：

让我们点开一个方法看下：

界面太大所以只截取部分，这里我们只需要输入请求参数，点击执行，就可以看奥执行结果如：

同时右边还有下载按钮可以直接下载到一个json格式的返回值。

通常各种方法在swagger的接口界面都会为我们对应生成参数，只需要填写值就可直接执行请求，以下是post请求，以application/json方式发起请求的示例：

总结：

    swagger2是不是很好用了，上面只演示了觉得用得上的注解，当然它还有一系列的注解帮助我们对接口和入参进行详细说明比如：

• @ApiImplicitParams：用在请求的方法上，表示一组参数说明

• @ApiImplicitParam：用在@ApiImplicitParams注解中，代表某一个具体参数，用于单个参数的各个信息说明

• @ApiResponses：用在请求的方法上，表示一组响应

• @ApiResponse：用在@ApiResponses中，表示响应的某个具体参数，用于对具体参数的各个方面进行说明

• @ApiModel：用于响应类上，表示一个返回响应数据的信息

• @ApiModelProperty：和@ApiModel搭配使用，用在响应类的属性上，描述响应类的属性信息

这些注解，可根据需要使用，通常只要参数定义的好，有具体的语义，我觉得不需要这么详细的备注，额外增加写注解的工作量。

怎么样，是不是很简单呢，有需要的小伙伴儿们，赶快试试吧，如果觉得好用，不妨帮我点个赞，鼓励鼓励我在分享的路上，永不止步哦...!