knife4j整合使用

每到项目验收或者给别人开放接口写接口文档就头疼的不行，参数多了还要一个一个去对；之前就想找有没有能到导出接口文档的工具，postman和swagger都不能实现。直到看到大佬推荐的 knife4j 。

使用：

使用和swagger类似。

1、在实体类中使用@ApiModel、@ApiModelProperty注解

2、controller中使用@Api、@ApiOperation、@ApiParam注解

第一步：在maven项目的pom.xml中引入Knife4j的依赖包，代码如下：

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>2.0.7</version>
</dependency>

第二步：创建Swagger配置依赖，代码如下：

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        //.title("swagger-bootstrap-ui-demo RESTful APIs")
                        .description("# swagger-bootstrap-ui-demo RESTful APIs")
                        .termsOfServiceUrl("http://www.xx.com/")
                        .contact("xx@qq.com")
                        .version("1.0")
                        .build())
                //分组名称
                .groupName("2.X版本")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.github.xiaoymin.knife4j.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

此时，启动Spring Boot工程，在浏览器中访问：http://localhost:17790/doc.html

如果项目中增加有权限认证的话，需要添加白名单。

实现WebMvcConfigurer

@Configuration
public class WebMvcConfigure extends WebMvcConfigurationSupport {

    @Bean
    public UserContextInterceptor userContextInterceptor() {
        return new UserContextInterceptor();
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(userContextInterceptor())
                .addPathPatterns("/**");
        registry.addInterceptor(new HandlerFilter()).addPathPatterns("/**");
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        if(System.getProperty("os.name").toLowerCase().contains("win")){
            registry.addResourceHandler("/uploads/**")
                    .addResourceLocations("File:D:\\datas\\");
        }else {
            registry.addResourceHandler("/uploads/**")
                    .addResourceLocations("/datas/");
        }
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }

}

SpringSecurity

secure:
  ignored:
    urls: #安全路径白名单
      - /doc.html
      - /swagger-ui/**
      - /swagger/**
      - /swagger-resources/**
      - /**/v3/api-docs

Shiro

在ShiroConfig中增加白名单

@Configuration
public class ShiroConfig {

    @Resource
    AuthService authService;

    /**
     * 自定义的Realm
     */
    @Bean(name = "myRealm")
    public MyRealm myRealm(@Qualifier("codLimitCredentialsMatcher") MyRetryLimitCredentialsMatcher matcher) {
        MyRealm myRealm = new MyRealm();
        myRealm.setCredentialsMatcher(matcher);
        return myRealm;
    }

    @Bean
    public DefaultWebSecurityManager securityManager(@Qualifier("codLimitCredentialsMatcher") MyRetryLimitCredentialsMatcher matcher) {
        DefaultWebSecurityManager securityManager = new DefaultWebSecurityManager();
        securityManager.setRealm(myRealm(matcher));
        return securityManager;
    }

    @Bean
    public ShiroFilterFactoryBean shirFilter(SecurityManager securityManager) {
        ShiroFilterFactoryBean shiroFilterFactoryBean = new ShiroFilterFactoryBean();
        shiroFilterFactoryBean.setSecurityManager(securityManager);
        //拦截器.
        Map<String, String> filterChainDefinitionMap = new LinkedHashMap<>();

        //从数据库中读出权限和URL
        List<Auth> urlPermsList = authService.getUrlAuth();
        for (Auth auth : urlPermsList) {
            if (StringUtils.isNotEmpty(auth.getUrl())) {
                filterChainDefinitionMap.put(auth.getUrl(), "perms[" + auth.getName() + "]");
            }
        }

        /**
         * anon  -- 所有url都都可以匿名访问
         * authc -- 需要认证才能进行访问
         */
        //swagger
        filterChainDefinitionMap.put("/swagger-ui.html", "anon");
        filterChainDefinitionMap.put("/webjars/**", "anon");
        filterChainDefinitionMap.put("/v2/**", "anon");
        filterChainDefinitionMap.put("/swagger-resources/**", "anon");
        filterChainDefinitionMap.put("/doc.html", "anon");
        
        filterChainDefinitionMap.put("/**", "authc");

        /**
         * @filtsMap: 过滤器配置
         * 由于前端ajax请求无法进行重定向，所以不能通过设置url重定向的方法来返回信息。
         * 在这里通过配置新的过滤器，并重写其中的方法来达到未登录或无状态时的信息返回。
         */
        LinkedHashMap<String, Filter> filtsMap = new LinkedHashMap<String, Filter>();
        filtsMap.put("authc", new LoginFilter());
        filtsMap.put("perms", new PermsAuthorizationFilter());
        shiroFilterFactoryBean.setFilters(filtsMap);

        shiroFilterFactoryBean.setFilterChainDefinitionMap(filterChainDefinitionMap);
        return shiroFilterFactoryBean;
    }

    /**
     * 密码匹配凭证管理器
     *
     * @注意 这里的加密算法 得跟添加用户时的加密算法一致
     * 这里采用md5散列一次，所以在工具类EncryptUtil中也md5散列一次
     */
    @Bean(name = "codLimitCredentialsMatcher")
    public MyRetryLimitCredentialsMatcher hashedCredentialsMatcher() {
        return new MyRetryLimitCredentialsMatcher();
    }
}

官方链接：

官网：https://doc.xiaominfo.com/knife4j/

官方文档：https://doc.xiaominfo.com/knife4j/documentation/

码云地址：https://gitee.com/xiaoym/knife4j

参考链接：

https://blog.csdn.net/qing_gee/article/details/122857385?utm_medium=distribute.pc_follow_feed_v2.none-task-blog-follow-2.nonecasedepth_1-utm_source=distribute.pc_follow_feed_v2.none-task-blog-follow-2.nonecase

https://blog.csdn.net/wind1_rain/article/details/108590462