为新项目做准备重新搭建环境，决定使用Springboot2+mybatis环境，使用shiro做权限管理，并搭配pagehelper，generator等。在配置Swagger2的时候出现访问时界面空白的坑，刚开始以为是配置的插件过多导致的不兼容，重新配置了其他环境，但问题依然存在，后来查找资料解决了问题。现在此作记录。目前使用Springboot 版本为 2.0.3.RELEASE。
一、springboot2导包（maven）：
在pom.xml中
<!--Swagger2--> <dependency><groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${springfox-swagger2.version}</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>${springfox-swagger2.version}</version> </dependency>
<springfox-swagger2.version>2.8.0</springfox-swagger2.version>
二、Swagger2配置
新建Swagger2配置文件Swagger2Config.java
配置文件Swagger2Config.java中：支持多个api文档
//注解开启 swagger2 功能 @EnableSwagger2 //注解标示,这是一个配置类,@Configuation注解包含了@Component注解 //可以不用在使用@Component注解标记这是个bean了 @Configuration @EnableWebMvc public class Swagger2Config implements WebMvcConfigurer { @Value("${base.location}")//项目初始目录 private String baseLocation; /** _ * 将__Swagger2 的__swagger-ui.html__加入资源路径下,__否则__Swagger2__静态页面不能访问。要想使资源能够访问，可以有两种方法 _ * 一：需要配置类继承__WebMvcConfigurationSupport _类，实现__addResourceHandlers__方法。 _ * _但是实现了__WebMvcConfigurationSupport__以后，_Spring Boot__的 _WebMvc__自动配置就会失效，具体表现比如访问不到 _ * _静态资源（js，css__等）了，这是因为__WebMvc__的自动配置都在__WebMvcAutoConfiguration__类中，但是类中有这个注解 _ * _@ConditionalOnMissingBean({WebMvcConfigurationSupport.class})，意思是一旦在容器中检测到 _ * WebMvcConfigurationSupport__这个类，WebMvcAutoConfiguration__类中的配置都不生效。 _ * 所以一旦我们自己写的配置类继承了__WebMvcConfigurationSupport，相当于容器中已经有了__WebMvcConfigurationSupport， _ * _所有默认配置都不会生效，都得自己在配置文件中配置。 _ * _二：继承__WebMvcConfigurer__接口，这里采用此方法 网上有人说使用该方法会导致__date__编译等问题，可能在配置文件中得到解决， _ * _本人没有碰到，不多做解释 _ * @param _registry _ _*/ _ @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); }
_/\*\*
_ * 通过 createRestApi__函数来构建一个__DocketBean _ * 函数名,可以随意命名,__喜欢什么命名就什么命名 _ * _接口文档默认访问路径__http://localhost:8080/swagger-ui.html__， _ * _配置文件中有配置此处为__http://localhost:8080/springboot2/swagger-ui.html _ * _注解说明参考博客：__https://blog.csdn.net/qq\_28009065/article/details/79104103__， _ */ @Bean public Docket commonDocket() { return new Docket(DocumentationType.SWAGGER_2) .groupName("通用API接口文档") .apiInfo(apiInfo("测试环境通用接口")) .pathMapping("/") .select() .apis(RequestHandlerSelectors.basePackage(baseLocation+".web.controller"))//指向自己的controller即可 .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(baseLocation+".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(baseLocation+".controller.company")) // .paths(PathSelectors.any()) // .build(); // } //设置文档信息 private ApiInfo apiInfo(String desc) { return new ApiInfoBuilder() //页面标题 .title(desc) //设置作者联系方式,可有可无 .contact(new Contact("chaoge", "https://my.csdn.net/xiaochaogge", "z28126308@163.com")) //版本号 .version("1.0") //描述 .description("API 描述") .build(); } }
/* 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):符合正则的路径 设置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 常用注解: 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中显示 */
在application.properties中（网上有人可能出现的date格式错误等问题，本人目前还没有出现此类问题，但是也贴出有关的配置供参考）
spring.jackson.serialization.indent_output=true spring.jackson.serialization.write-dates-as-timestamps=true spring.http.converters.preferred-json-mapper=jackson #设置时区 spring.jackson.time-zone=GMT+8 spring.jackson.date-format=yyyy-MM-dd HH:mm:ss spring.jackson.joda-date-time-format=yyyy-MM-dd HH:mm:ss
新建WebMVCCongig.java类实现WebMvcConfigurer接口（没有这步操作Swagger2已经可以使用）设置跨域请求
@Configuration public class WebMVCConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry){ registry.addResourceHandler("/static/**") .addResourceLocations("classpath:/static/"); }
@Override
public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/**")//设置允许跨域的路径 .allowedOrigins("*")//设置允许跨域请求的域名 .allowCredentials(true)//是否允许证书 不再默认开启 .allowedMethods("GET", "POST", "PUT", "DELETE")//设置允许的方法 .maxAge(3600);//跨域允许时间 } }
三、在controller类中
@CrossOrigin @RestController @RequestMapping("/test") @Api(tags="测试类",value="测试类") public class TestController { @ApiOperation(value="【PC端】提交订单", notes="提交一组识别的标签id，返回生成的订单详情") @RequestMapping(value = "/test/{id}", method = RequestMethod.POST, produces = "application/json;charset=UTF-8") public Integer test(@PathVariable Integer id){ System.out.println(id); return id; } }
四、效果图
