Swagger集成方法以及常见问题

Spring mvc后端项目如果集成swagger，可以很方便的进行接口调试，以下是自己在老项目中集成swagger的步骤，非springboot项目。其实原理一样。废话不多说，直接上步骤。

1.添加maven依赖

	<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>

2.加入包扫描配置类

package xxxx;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.schema.ModelRef;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Parameter;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;
import java.util.List;



@Configuration
@EnableSwagger2
public class PrototypeSwaggerConfigure {
    @Bean
    public Docket createRestApi() {
    	
    	ParameterBuilder ticketPar = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
    	ticketPar.name("XX-Token").description("用户名/密码/年度")
    	.modelRef(new ModelRef("string")).parameterType("header")
    	.required(false).build(); //header中的ticket参数非必填，传空也可以
    	pars.add( ticketPar.build());    //根据每个方法名也知道当前方法在设置什么参数

        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("国企管理系统接口")
                .apiInfo(apiInfo())
                .select()
                // 扫描的包所在位置
                .apis(RequestHandlerSelectors.basePackage("com.xxx"))
                // 扫描的 URL 规则
                .paths(PathSelectors.any())
                .build().globalOperationParameters(pars)
                .ignoredParameterTypes(CurrentUser.class);
    }


    private ApiInfo apiInfo() {
        // 联系信息
        return new ApiInfoBuilder()
                // 大标题
                .title("")
                // 描述
                .description("")
                // 服务条款 URL
                .termsOfServiceUrl("")
                // 版本
                .version("")
                .build();
    }
}

3.常见问题

3.1服务无法启动

如果有如下报错信息

	Error creating bean with name 'webMvcRequestHandlerProvider' defined in URL

在spring.xml中找到component-scan标签,加入exclude-filter

<context:component-scan base-package="xxx">
        <context:exclude-filter type="assignable" expression="xxx.SwaggerConfig"/>
</context:component-scan>

3.2显示不了接口

如果配拦截器拦截，需要进行排除配置，如下：

<!-- 增加权限验证拦截器,处理权限问题。 -->
<mvc:interceptors>
	<mvc:interceptor>
		<mvc:mapping path="/**" />
		<mvc:exclude-mapping path="/swagger-resources/**" />
		<mvc:exclude-mapping path="/webjars/**" />
		<mvc:exclude-mapping path="/v2/**" />
		<mvc:exclude-mapping path="/swagger-ui.html/**" />
		<mvc:exclude-mapping path="/swagger-ui.html/**" />
		<mvc:exclude-mapping path="/api" />
		<mvc:exclude-mapping path="/api-docs" />
		<mvc:exclude-mapping path="/api-docs/**" />
		<bean class="xxx.AuthorizationInterceptor" />
	</mvc:interceptor>
</mvc:interceptors>

4.最简单的使用

@Api(tags = "类名注释")
@RestController
@RequestMapping("/aa")
public class XXXController {
    @ApiOperation ("方法注释")
    @GetMapping("/xxx/{yy}")
    public Response getInfo(@PathVariable String xxx, ) {
        return new Response ().success (list);
    }
}