SpringMVC+Security项目集成文档Knife4j的详细方法

需求说明

有一个JavaWeb-SpringMVC的项目（还用到了SpringSecurity）,也需要接入Knife4j文档，按照官方的示例（最后的更新日期还是几年前的），并没有成功，结合自己摸索和实践，成功集成好了，故写出来详细的步骤，供参考。

实现步骤

• pom.xml增加如下依赖（我这里的情况是需要加载jackson的相关的3个依赖包，看实际情况）：

<!-- knife4j-spring-mvc -->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-mvc</artifactId>
    <version>2.0.9</version>
</dependency>

<!-- json -->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.13.4.2</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-annotations</artifactId>
    <version>2.13.4</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>2.13.4</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-joda</artifactId>
    <version>2.13.4</version>
</dependency>

spring.xml 增加如下内容：

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:context="http://www.springframework.org/schema/context"
       xmlns:p="http://www.springframework.org/schema/p" xmlns:mvc="http://www.springframework.org/schema/mvc"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans.xsd
    http://www.springframework.org/schema/context
    http://www.springframework.org/schema/context/spring-context.xsd
    http://www.springframework.org/schema/mvc
    http://www.springframework.org/schema/mvc/spring-mvc-4.0.xsd">

    <!-- 其他配置省略，只贴出关于knife4j相关的配置部分 -->
    
    <!-- 线上环境如果不需要knife4j文档，就把这三行注释或删了 -->
    <mvc:resources location="classpath:/META-INF/resources/" mapping="doc.html"/>
    <mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>
    <bean id="Knife4jConfiguration" class="com.example.test.Knife4jConfiguration"></bean>


    <!-- 对模型视图名称的解析，即在模型视图名称添加前后缀 -->
    <bean
            class="org.springframework.web.servlet.view.InternalResourceViewResolver"
            p:prefix="/WEB-INF/views/" p:suffix=".jsp" /><!-- p:prefix="/WEB-INF/views/" -->

    <!-- one of the properties available; the maximum file size in bytes (2097152 B = 2 MB)
    -->
    <bean id="multipartResolver"
          class="org.springframework.web.multipart.commons.CommonsMultipartResolver"
          p:defaultEncoding="utf-8" p:maxUploadSize="10485760000"
          p:maxInMemorySize="40960" />
</beans>

新增Knife4j的配置文件Knife4jConfiguration.java

package com.example.test;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {

    @Bean(value = "dockerBean")
    public Docket dockerBean() {
        //指定使用Swagger2规范
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        //描述字段支持Markdown语法
                        .description("# Knife4j RESTful APIs")
                        .version("1.0")
                        .build())
                //分组名称
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.test.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
}

如果你的项目还集成了SpringSecurity，需要在SpringSecurity的配置文件中排除knife4j相关的url路径

@EnableWebSecurity
public class SecurityConfiguration extends WebSecurityConfigurerAdapter {

    // 其他代码省略

    @Override
    public void configure(WebSecurity web) {
        
        // swagger 相关路径排除
        web.ignoring().antMatchers("/swagger**/**", "/webjars/**", "/v3/**","/v2/**", "/doc.html");
    }

}