大杀器！SpringMVC集成Swagger,解决后端接口和功能测试问题！

不会或不熟悉前端？没关系！集成Swagger轻松帮助你！

1.首先映入相关JAR包，我这里是maven项目，所以直接在pom文件引入。

<!--Swagger start-->        
<!-- springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.5.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.5.0</version>
</dependency>
<!-- springfox-swagger2 dependencies -->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-annotations</artifactId>
    <version>2.9.5</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.9.5</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>2.9.5</version>
</dependency>
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>15.0</version>
</dependency>
<dependency>
    <groupId>com.fasterxml</groupId>
    <artifactId>classmate</artifactId>
    <version>1.1.0</version>
</dependency>
<!--swagger end-->

 

 如果你的pom文件有引入和包含引入的包，注意排包 swagger有多个版本 ，不同版本注解也有差异，建议使用和本文相同的版本。

2.复制一下swaggger配置文件，放到项目中

package cn.sevendream.mmall.config;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
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;

/**
 * ${DESCRIPTION}
 *
 * @author zhangxue
 * @date 2018-10-30 下午5:02
 */

@Component
@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan("cn.sevendream.mmall.controller")
public class Swagger2Config {

    @Bean
    public Docket createAPI() {
        return new Docket(DocumentationType.SWAGGER_2).forCodeGeneration(true).select().apis(RequestHandlerSelectors.any())
                //过滤生成链接
                .paths(PathSelectors.any()).build().apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {

        Contact contact=new Contact("Simon","https://blog.csdn.net/zx03070723","345623958@qq.com");
        ApiInfo apiInfo = new ApiInfoBuilder().license("Apache License Version 2.0").title("Swagger 集成测试").description("Swagger API Teste").contact(contact).version("1.0").build();

        return apiInfo;
    }
}

 

3.dispatcher-servlet.xml配置扫描加载

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:mvc="http://www.springframework.org/schema/mvc"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd
	    http://www.springframework.org/schema/mvc
	    http://www.springframework.org/schema/mvc/spring-mvc.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">


    <mvc:annotation-driven>
        <mvc:message-converters>
            <bean class="org.springframework.http.converter.StringHttpMessageConverter">
                <property name="supportedMediaTypes">
                    <list>
                        <value>text/plain;charset=UTF-8</value>
                        <value>text/html;charset=UTF-8</value>
                    </list>
                </property>
            </bean>
            <bean class="org.springframework.http.converter.json.MappingJackson2HttpMessageConverter">
                <property name="supportedMediaTypes">
                    <list>
                        <value>application/json;charset=UTF-8</value>
                    </list>
                </property>
            </bean>
        </mvc:message-converters>
    </mvc:annotation-driven>
    <!--根据servlet请求，找到对应controller的对应方法-->
    <context:component-scan base-package="cn.sevendream.mmall.controller"/>
    <!-- 容器默认的DefaultServletHandler处理 所有静态内容与无RequestMapping处理的URL-->
    <mvc:default-servlet-handler/>
    <!--swagger相关-->
    <context:component-scan base-package="springfox"/>
    <mvc:annotation-driven />
    <mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
    <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>
</beans>

4.同步前三步，就配置好了 ，剩下的就是开始使用swagger注解，启动项目进行测试了。

先介绍下swagger的注解

常用注解： 
- @Api()用于类； 
表示标识这个类是swagger的资源 
- @ApiOperation()用于方法； 
表示一个http请求的操作 
- @ApiParam()用于方法，参数，字段说明； 
表示对参数的添加元数据（说明或是否必填等） 
- @ApiModel()用于类 
表示对类进行说明，用于参数用实体类接收 
- @ApiModelProperty()用于方法，字段 
表示对model属性的说明或者数据操作更改 
- @ApiIgnore()用于类，方法，方法参数 
表示这个方法或者类被忽略 
- @ApiImplicitParam() 用于方法 
表示单独的请求参数 
- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

以下是我项目中的示例。

 

 

@RequestMapping(value = "register", method = RequestMethod.POST)
@ApiOperation(value = "注册")
public ServerResponse<String> register(@RequestBody @ApiParam(value = "用户对象") User user{
    return iUserService.register(user);
}

 

 

@RequestMapping(value = "check_valid", method = RequestMethod.POST)
@ApiOperation(value = "校验用户名/邮箱是否有效")
@ApiImplicitParams({@ApiImplicitParam(name = "value", value = "校验值", paramType = "query",     
                        dataType = "string")
                  , @ApiImplicitParam(name = "type", value = "类型码值【username,email】", 
                        paramType = "query", dataType = "string")} )
public ServerResponse<String> checkValid(@RequestParam("value") String value,     
                                         @RequestParam("type") String type) {
    return iUserService.checkValid(value, type);
}

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "用户对象user",description = "用户对象user")
public class User {
    @ApiModelProperty(value = "用户主键",hidden = true)
    private Integer id;
    @ApiModelProperty(value = "账号",name="username",example = "Simon")
    private String username;
    @ApiModelProperty(value = "密码",example = "111111")
    private String password;
    @ApiModelProperty(value = "邮箱",example = "111111@qq.com")
    private String email;
    @ApiModelProperty(value = "联系方式",example = "13811111111")
    private String phone;
    @ApiModelProperty(value = "问题",example = "我的名字")
    private String question;
    @ApiModelProperty(value = "答案",example = "Simon")
    private String answer;
    @ApiModelProperty(value = "角色",hidden = true)
    private Integer role;
    @ApiModelProperty(value = "创建时间")
    private Date createTime;
    @ApiModelProperty(value = "更新时间")
    private Date updateTime;

}