一、介绍knife4j

增强版本的Swagger 前端UI,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端。

二、Spring Boot 整合knife4j

第一步，在Maven中的pom.xml文件引入:

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用时请在maven中央仓库搜索最新版本号-->
    <version>2.0.4</version>
</dependency>

第二步，增加配置类，主要添加@Configuration、EnableSwagger2、@EnableKnife4j以及@Import(BeanValidatorPluginsConfiguration.class)注解：

@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class Swagger2Config {
    
    
    @Bean
    public Docket createRestApi(){
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)
                .select()
                //为当前包下controller生成API文档
                .apis(RequestHandlerSelectors.basePackage("com.dream"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }
    private ApiInfo apiInfo() {
    
    
        return new ApiInfoBuilder()
                .title("SwaggerUI")
                .description("mall-tiny")
                .contact("macro")
                .version("1.0")
                .build();
    }
    private List<ApiKey> securitySchemes() {
    
    
        //设置请求头信息
        List<ApiKey> result = new ArrayList<>();
        ApiKey apiKey = new ApiKey("Authorization", "Authorization", "header");
        result.add(apiKey);
        return result;
    }
    private List<SecurityContext> securityContexts() {
    
    
        //设置需要登录认证的路径
        List<SecurityContext> result = new ArrayList<>();
        result.add(getContextByPath("/misty/.*"));
        return result;
    }
    private SecurityContext getContextByPath(String pathRegex){
    
    
        return SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.regex(pathRegex))
                .build();
    }
    private List<SecurityReference> defaultAuth() {
    
    
        List<SecurityReference> result = new ArrayList<>();
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        result.add(new SecurityReference("Authorization", authorizationScopes));
        return result;
    }
}

第三步，如果项目中没有使用shiro、SpringSecurity 等权限框架，可以访问，如下地址：

http://localhost:8080/doc.html

第四步，如果使用了权限框架，如shiro、SpringSecurity，需要添加配置：

1、实现WebMvcConfigurer

@SpringBootApplication
public class SwaggerBootstrapUiDemoApplication  implements WebMvcConfigurer{
    
    
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
    
    
        registry.addResourceHandler("doc.html").addResourceLocations("classpath*:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath*:/META-INF/resources/webjars/");
    }
}

注意：楼主在这里遇到一个很大的坑，就是如果我使用classpath*：，会一直报错；修改为classpath后，恢复正常。

2、楼主用的shiro,需要配置，放开相应的路径：

@Bean
protected ShiroFilterChainDefinition shiroFilterChainDefinition() {
    
    
    DefaultShiroFilterChainDefinition chainDefinition = new DefaultShiroFilterChainDefinition();
    chainDefinition.addPathDefinition("/doc.html", "anon");
    chainDefinition.addPathDefinition("/webjars/**/**", "anon");
    return chainDefinition;
}

第五步，展示结果：

首页

实体页

knife4j 的官网地址

补充一点知识：

classpath和classpath*区别：

classpath：默认只会在你项目的class路径中查找文件。
classpath*：默认不仅包含class路径，还包括jar文件中（class路径）进行查找。
注意：
使用classpath*:Spring需要遍历所有的classpath，所以加载速度是很慢的；故在设计中，应该尽可能划分好资源文件所在的路径，尽量避免使用classpath*。

classpath*的使用：

当项目中有多个classpath路径，并同时加载多个classpath路径下（此种情况多数不会遇到）的文件，就发挥了作用，如果不加，则表示仅仅加载第一个classpath路径。

Springboot整合knife4j与shiro