swagger集成

springboot与swagger集成踩过的坑

概述

​ 最近在做集成swagger的时候，发现了新版的swagger有好多的坑。建议使用swagger 2.8.0版本。

集成

配置pom.xml

<!-- swagger 2.8.0 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.8.0</version>
			<exclusions>
				<exclusion>
					<groupId>org.springframework</groupId>
  					<artifactId>spring-core</artifactId>
				</exclusion>
				<exclusion>
					<groupId>org.springframework</groupId>
  					<artifactId>spring-beans</artifactId>
				</exclusion>
				<exclusion>
					<groupId>org.springframework</groupId>
  					<artifactId>spring-context</artifactId>
				</exclusion>
				<exclusion>
					<groupId>org.springframework</groupId>
  					<artifactId>spring-context-support</artifactId>
				</exclusion>
				<exclusion>
					<groupId>org.springframework</groupId>
  					<artifactId>spring-aop</artifactId>
				</exclusion>
				<exclusion>
					<groupId>org.springframework</groupId>
  					<artifactId>spring-tx</artifactId>
				</exclusion>
				<exclusion>
					<groupId>org.springframework</groupId>
  					<artifactId>spring-orm</artifactId>
				</exclusion>
				<exclusion>
					<groupId>org.springframework</groupId>
  					<artifactId>spring-jdbc</artifactId>
				</exclusion>
				<exclusion>
					<groupId>org.springframework</groupId>
  					<artifactId>spring-web</artifactId>
				</exclusion>
				<exclusion>
					<groupId>org.springframework</groupId>
  					<artifactId>spring-webmvc</artifactId>
				</exclusion>
				<exclusion>
					<groupId>org.springframework</groupId>
  					<artifactId>spring-oxm</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId> 
			<version>2.8.0</version>
		</dependency>

如上图，第一个坑就是这样产生的，为什么要去掉swagger里面的spring的配置。因为swagger里面相关的spring包实在太老了，都是spring4版本的东西。然后一般springboot2.0以上都是用spring5以上的，因此会产生冲突。

swagger配置类

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.ApiInfo;
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("/")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.csair.ehome.newplatform.vote.management.web.controller"))
                .paths(PathSelectors.any())
                .build();
    }
	
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
	    .title("xxx调查后台接口文档")
	    .description("xxx调查后台接口，详细信息......")
	    .version("1.0")
	    .contact(new Contact("李小明","www.tb.com","lxming@tb.com"))
	    .license("The csair License")
	    .licenseUrl("www.csair.com")
	    .build();
	}
}

然后就可以打开http://localhost:8080/swagger-ui.html了，有配置context的url加上你的context，当然想要看详尽说明的文档，还要在controller里面加上@Api(tags="导出问卷报表接口") ，方法加上@ApiOperation("获取已发布过的问卷列表") ，方法参数加上@ApiParam这些注解，具体学一下swagger常用的注解就行了。

踩过的坑

​上面配置完成，可以说是非常的简单。但是，我刚开始用的swagger是2.9.2的，可以说是巨坑。

1. 网上的都是直接用，当时会产生spring版本冲突，要去掉swagger里面的版本
2. swagger 2.9.2打不开http://localhost:8080/swagger-ui.html这个页面，晕，现在也搞不清是怎么回事，当时还直接将springfox-swagger-ui.2.9.2.jar这个包解压，解压后将里面META-INF/resources/的东西放到自己项目的META-INF/resources下，这样跑起来后也能跑得通。但是问题还是继续再来
3. 跑通后，发现每当打开这个http://localhost:8080/swagger-ui.html页面，后台就会报错，真的是恶心。首先，会报一个nullPointException，其次，页面会请求了两个不存在的URL，一个是你后台项目的原路径，也就是http://localhost:8080，第二个路径是什么也忘了，好像是csrf什么的，导致后台日志非常难看，各种报错，虽然对功能是完全没有影响。网上还会教你怎么去掉这个空指针异常，方法是换swagger某些东西版本。

总结

说了这么多坑，其实很简单，就是用回swagger 2.8.0的版本就行了，然后排除swagger里面的spring版本。实在没想到2.9.2有这么问题