为了节省开发人员的时间与成本,swagger插件油然而生,省去您写开发文档的时间好好去快乐的玩耍,不说废话,接下来我将使用github上比较受欢迎的swagger-bootstrap-ui插件进行说明讲解,可能与swagger在配置上有所不同,但是原理差不过,只是在资源文件的过滤方面有所不同,特别是结合了过滤spring security或者是shiro的有尤为注意:
添加依赖
<properties> <java.version>1.8</java.version> <shiro.version>1.4.0</shiro.version> <swagger2.version>2.9.2</swagger2.version> </properties> <!--swagger api文档 start--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>${swagger2.version}</version> <exclusions> <exclusion> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> </exclusion> <!--<exclusion>--> <!--<artifactId>guava</artifactId>--> <!--<groupId>com.google.guava</groupId>--> <!--</exclusion>--> </exclusions> </dependency> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.0</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> <version>1.5.21</version> <exclusions> <exclusion> <artifactId>swagger-annotations</artifactId> <groupId>io.swagger</groupId> </exclusion> </exclusions> </dependency> <!--shiro安全框架 start--> <dependency> <groupId>org.apache.shiro</groupId> <artifactId>shiro-core</artifactId> <version>${shiro.version}</version> </dependency> <dependency> <groupId>org.apache.shiro</groupId> <artifactId>shiro-web</artifactId> <version>${shiro.version}</version> </dependency> <dependency> <groupId>org.apache.shiro</groupId> <artifactId>shiro-ehcache</artifactId> <version>${shiro.version}</version> </dependency> <dependency> <groupId>org.apache.shiro</groupId> <artifactId>shiro-spring</artifactId> <version>${shiro.version}</version> </dependency>
swagger结合shiro代码分析
由于spring默认是不开放资源文件(如图片,html文件),所以我们要添加一个配置类,让它开放:
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration; import org.springframework.web.cors.CorsConfiguration; import org.springframework.web.cors.UrlBasedCorsConfigurationSource; import org.springframework.web.filter.CorsFilter; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport; import javax.servlet.ServletContext; @Configuration public class WebMvcConfiguration extends WebMvcConfigurationSupport { // 请在properties文件中添加该属性,判断是否开启swagger @Value("${swagger.enable}") private boolean swaggerEnable; @Override protected void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/static/**") .addResourceLocations("classpath:/static/"); registry.addResourceHandler("/logo.png") .addResourceLocations("classpath:/"); registry.addResourceHandler("/favicon.ico") .addResourceLocations("classpath:/"); // 判断是否启用swagger文档界面,启用则会开放这些资源,让开发者能够访问到 if (swaggerEnable) { registry.addResourceHandler("/doc.html") .addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**") .addResourceLocations("classpath:/META-INF/resources/webjars/"); } super.addResourceHandlers(registry); } @SuppressWarnings({"unchecked"}) @Bean public FilterRegistrationBean normalCorsFilter() { UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); CorsConfiguration config = new CorsConfiguration(); config.setAllowCredentials(true); // 设置你要允许的网站域名,如果全允许则设为 * config.addAllowedOrigin("*"); // 如果要限制 HEADER 或 METHOD 请自行更改 config.addAllowedHeader("*"); config.addAllowedMethod("*"); source.registerCorsConfiguration("/**", config); FilterRegistrationBean bean = new FilterRegistrationBean(new CorsFilter(source)); // 这个顺序很重要哦,为避免麻烦请设置在最前面 bean.setOrder(0); return bean; } @Override public void setServletContext(ServletContext servletContext) { servletContext.setSessionTimeout(12*60*60); super.setServletContext(servletContext); } }
import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * 仅在测试与开发环境使用 * @author Anthony */ @Configuration @EnableSwagger2 @EnableSwaggerBootstrapUI @Profile({"dev", "test"}) // 当你有多个properties配置文件时,添加 public class SwaggerConfiguration { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.shiro.demo.CRUD.controller")) // 最后面这个是你Controller所在包的位置 .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("shiro权限控制") .description("restful风格") .version("1.0") .build(); } }
由于我最近在学习shiro,所以就以shiro为基础讲解swagger的用法,接下来是防止shiro过滤swagger文件的配置,如果没有使用shiro或者是spring security的请忽略,谢谢:
/** 创建一个配置类,创建一个叫做shiroFilter的bean,这就是shiro的过滤器配置类,设置对应的过滤条件和跳转条件,下面我只写了swagger中不需要shiro过滤的文件 **/
@Bean(name = "shiroFilter")
public ShiroFilterFactoryBean shiroFilterFactoryBean(@Qualifier("securityManager") SecurityManager securityManager) { ShiroFilterFactoryBean shiroFilterFactoryBean = new ShiroFilterFactoryBean(); // 配置不会被拦截的链接 顺序判断 filterChainDefinitionMap.put("/static/**", "anon"); filterChainDefinitionMap.put("/login", "anon"); //被shiro拦截的swagger资源放行 filterChainDefinitionMap.put("/doc.html/**", "anon"); filterChainDefinitionMap.put("/swagger-resources/**", "anon"); filterChainDefinitionMap.put("/v2/api-docs/**", "anon"); filterChainDefinitionMap.put("/webjars/**", "anon"); filterChainDefinitionMap.put("/swagger-resources/configuration/ui/**", "anon"); filterChainDefinitionMap.put("/swagger-resources/configuration/security/**", "anon"); shiroFilterFactoryBean.setFilterChainDefinitionMap(filterChainDefinitionMap); return shiroFilterFactoryBean; }
swagger-bootstrap-ui是集成了swagger并对其进行拓展的接口文档插件,推荐使用
效果演示:
这篇主要讲解shiro和swagger的结合。