SpringMVC注解配置Swagger2步骤及相关知识点

Swagger2的功能不多说了，百度一下随处可见，配置步骤也十分简单，但一些点百度到的很多都不太详细，个人进行了一些补充

1、pom.xml添加swagger2依赖（个人一般直接到http://search.maven.org/搜索artifactid点最新版本copy到pom里）

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

2、添加设置swagger2配置类

package pers.graduation.config;

import com.google.common.collect.Sets;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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;

/**
 * Created by Wilson on 2017/5/2.
 */
@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan(basePackages = "pers.graduation.controller")
public class SwaggerConfig extends WebMvcConfigurationSupport {
    @Bean
    public Docket commonDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("通用API接口文档")
                .apiInfo(apiInfo("提供通用接口"))
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("pers.graduation.controller.common"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket normalUserDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("普通用户API文档")
                .apiInfo(apiInfo("提供普通用户接口"))
                .protocols(Sets.newHashSet("https","http"))
                .produces(Sets.newHashSet("html/text"))
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("pers.graduation.controller.candidate"))//设置生成的Docket对应的Controller为candidate下的所有Controller
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket companyUserDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("企业用户API接口文档")
                .apiInfo(apiInfo("提供企业用户接口"))
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("pers.graduation.controller.company"))
                .paths(PathSelectors.any())
                .build();
    }
	//设置文档信息
    private ApiInfo apiInfo(String desc) {
        return new ApiInfo(
                "Test Website",				//标题名称
                desc,					//文档描述
                "1.0.1",				//版本号，自定义
                "http://blog.csdn.net/z28126308",	//许可人URL
                contact(),				//联系方式实体类
                "Wilson",				//许可人，许可证
                "http://blog.csdn.net/z28126308");	//许可URL
    }
	//设置联系方式
    private Contact contact() {
        return new Contact("Wilson", "http://blog.csdn.net/z28126308", "z28126308@163.com");
    }
}

Docket类的方法：

Docket groupName(String var):设置栏目名

Docket apiInfo(ApiInfo apiInfo):设置文档信息

Docket pathMapping(String path):设置api根路径

Docket protocols(Set<String> protocols):设置协议，Sets为com.goolge.common下的类，Sets.newHashSet("https","http")相当于new HashSet(){{add("https");add("http");}};

ApiSelectorBuilder select():初始化并返回一个API选择构造器

ApiSelectorBuilder类的方法：

ApiSelectorBuilder apis(Predicate<RequestHandler> selector):添加选择条件并返回添加后的ApiSelectorBuilder对象

ApiSelectorBuilder paths(Predicate<String> selector):设置路径筛选，该方法中含一句pathSelector = and(pathSelector, selector);表明条件为相与

RequestHandlerSelectors类的方法：

Predicate<RequestHandler> any()：返回包含所有满足条件的请求处理器的断言，该断言总为true

Predicate<RequestHandler> none()：返回不满足条件的请求处理器的断言,该断言总为false

Predicate<RequestHandler> basePackage(final String basePackage)：返回一个断言(Predicate)，该断言包含所有匹配basePackage下所有类的请求路径的请求处理器

PathSelectors类的方法：

Predicate<String> any():满足条件的路径，该断言总为true

Predicate<String> none():不满足条件的路径,该断言总为false

Predicate<String> regex(final String pathRegex):符合正则的路径

不讲太多，有兴趣的去看源码

3、设置swagger-ui.html默认路径，servlet的配置文件添加

<mvc:annotation-driven></mvc:annotation-driven>
<mvc:resources mapping="/webjars/**" location="classpath:/META-INF/resources/webjars"/>

swagger-ui.html位于springfox-swagger-ui jar包中的META-INF/resources/目录下，项目编译后swagger-ui.html将添加到classpath的/META-INF/resources/下，所以添加mapping="/webjars/**" 可通过localhost:端口号/项目名/swagger-ui.html打开SwaggerUI

4、常用注解

Swagger所有注解并非必须，若不加就只显示类目/方法名/参数名没有注释而已，但若注解中含@ApiParam不对应@RequestParam将无效果

@Api:注解controller，value为@RequestMapping路径

@ApiOperation:注解方法，value为简要描述,notes为全面描述,hidden=true Swagger将不显示该方法，默认为false

@ApiParam:注解参数,hidden=true Swagger参数列表将不显示该参数,name对应参数名，value为注释，defaultValue设置默认值,allowableValues设置范围值,required设置参数是否必须，默认为false

@ApiModel:注解Model

@ApiModelProperty:注解Model下的属性，当前端传过来的是一个对象时swagger中该对象的属性注解就是ApiModelProperty中的value

@ApiIgnore:注解类、参数、方法，注解后将不在Swagger UI中显示

效果图（若要传送对象作为参数，只需添加@ModelAttribute或@RequestBody）：

传送对象参数：

model:

private String telephone;

@Column
private String email;

@Column
private Long companyId;

@Transient
private ComCompany comCompany;

@Transient
private List<PositionWelfare> welfareList;

Controller方法:

@ResponseBody
@RequestMapping(value = "/per-addPosition", method = RequestMethod.POST)
@ApiOperation(value = "添加职位")
public Object addPosition(@ModelAttribute ComPosition position, @RequestParam String[] welfareName) {

Swagger