knifej文档生成工具基础讲解

在我们日常的开发中，接口文档是不可或缺的一环，但编写接口文档是一件耽误效率的事情，特别是不同的开发人员编写的接口文档总有或多或少的差异，这时候，一个统一风格，规范的接口文档编辑工具就出现了

knifej作为一个swagger2的增强版工具，我们主要讲解它的使用和相关配置，在开始之前，需要做的准备工作如下

完成基本的springboot的框架搭建

完成上述工作后，我们首先将相关依赖导入我们pom文件内

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

我们创建一个包config，在包内创建我们的knifej配置类，具体代码如下

package com.example.mallsystem.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.ArrayList;

@Configuration
@EnableSwagger2
@EnableKnife4j
public class KnifejConfig {
    @Bean
    public Docket docket() {
        //指定使用Swagger2规范
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //分组名称
                .groupName("测试大屏展示")
                .enable(true)
                .select()
                //指定扫描包的路径
                .apis(RequestHandlerSelectors.basePackage("com.example.mallsystem"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        //生成文档的一些基础信息
        return new ApiInfo("测试",
                "测试接口文档",
                "v1.0",
                "",
                new Contact("mzl", "http://Mall/test", "3356477560@qq.com"),  //作者信息

                "Apache 2.0",
                "Http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList<>());
    }
}

在创建完成我们的knifej的配置类后，我们启动我们的Springboot项目，打开网站http://localhost:8080/doc.html

注意端口号为本身项目的端口号，如果配置有统一路径 context-path，则需要在端口号后添加上统一路径

这时候有些同学会发现到这一步网站会打不开，报错，这就是文档编辑器的一个大坑，如果是前后端分离的项目，配置有拦截器等功能，会出现拦截器将文档编辑器的地址拦截的情况，这时候我们需要配置过滤请求，将文档编辑器的请求放行，代码如下

package com.example.mallsystem.config;

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;

//定义过滤器
@Configuration
public class CorsConfig {
    @Bean
    public CorsFilter corsFilter() {
        CorsConfiguration config = new CorsConfiguration();
        config.addAllowedOrigin("*");
        config.setAllowCredentials(true);
        config.addAllowedMethod("*");
        config.addAllowedHeader("*");
        UrlBasedCorsConfigurationSource configSource = new UrlBasedCorsConfigurationSource();
        configSource.registerCorsConfiguration("/**", config);
        return new CorsFilter(configSource);
    }
}

package com.example.mallsystem.config;

import javax.servlet.*;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

/**
 * 配置过滤器
 */
public class CooCorsFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        //*号表示对所有请求都允许跨域访问
        HttpServletResponse res = (HttpServletResponse) response;
        res.addHeader("Access-Control-Allow-Credentials", "true");
        res.addHeader("Access-Control-Allow-Origin", "*");
        res.addHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, PUT");
        res.addHeader("Access-Control-Allow-Headers", "Content-Type,X-CAF-Authorization-Token,sessionToken,X-TOKEN");
        if (((HttpServletRequest) request).getMethod().equals("OPTIONS")) {
            response.getWriter().println("Success");
            return;
        }
        chain.doFilter(request, response);
    }

    @Override
    public void destroy() {

    }

    @Override
    public void init(FilterConfig filterConfig) throws ServletException {

    }
}

将过滤器配置完成后就可以通过刚才的网址进入我们的文档生成网站了