knife4j文档请求异常_接口文档从Swagger升级成knife4j使用教程

Swagger应该是大部分Java程序员都有听说过或者使用过，不过呢，我觉得Swagger的界面使用起来有太好用，声明仅代表我的个人观点。

Knife4j是一个为Swagger接口文档赋能的工具，提供了我认为更加良好的操作体验。截止2020-11-02，版本已经升级到Knife4j 2.0.7了。

各版本信息

本文使用的版本是2.0.2版本，接下去我们介绍下这么接入knife4j吧。

接入knife4j步骤

1.引入依赖

在pom文件中引入以下两部分。

                        com.github.xiaoymin            knife4j-dependencies            2.0.2            pom            import            

    com.github.xiaoymin    knife4j-spring-boot-starter

dependencyManagement部分定义了引入的knife4j相关模块的版本。

dependency部分引入了具体的knife4j-spring-boot-starter包。

注意不需要再引入swagger2的其他依赖了。2.定义一个配置类

package com.huangtl.app.config;import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;import com.google.common.base.Predicate;import com.google.common.base.Predicates;import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import org.springframework.context.annotation.Import;import org.springframework.context.annotation.Profile;import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;import springfox.documentation.RequestHandler;import springfox.documentation.builders.ApiInfoBuilder;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.service.ApiInfo;import springfox.documentation.service.ApiKey;import springfox.documentation.service.AuthorizationScope;import springfox.documentation.service.SecurityReference;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spi.service.contexts.SecurityContext;import springfox.documentation.spring.web.plugins.Docket;import springfox.documentation.swagger2.annotations.EnableSwagger2;import java.util.ArrayList;import java.util.List;/*** 接口文档配置，浏览器访问：http://localhost:8888/doc.html*/@EnableSwagger2@Configuration@EnableKnife4j@Profile("dev")@Import(BeanValidatorPluginsConfiguration.class)public class SwaggerConfig {    @Bean("测试平台")    public Docket createRestApi() {        Predicate selector1 = RequestHandlerSelectors.basePackage("com.huangtl.app.controller");        return new Docket(DocumentationType.SWAGGER_2)                .groupName("测试平台")                .apiInfo(apiInfo())                .select()                .apis(Predicates.or(selector1))                .paths(PathSelectors.any())                .build()                .securityContexts(securityContext())                .securitySchemes(securitySchemes())                ;    }    private ApiInfo apiInfo() {        return new ApiInfoBuilder()                .title("测试平台 RESTful APIs")                .description("测试平台 api接口文档")                .version("1.0")                .build();    }    private List securitySchemes() {        List list = new ArrayList();        list.add(new ApiKey("loginToken", "loginToken", "header"));        return list;    }    private List securityContext() {        List list = new ArrayList();        SecurityContext securityContext = SecurityContext.builder()                .securityReferences(securityReferences())                .forPaths(PathSelectors.regex("/.*"))                .build();        list.add(securityContext);        return list;    }    List securityReferences() {        AuthorizationScope[] authorizationScopes = new AuthorizationScope[]{new AuthorizationScope("global", "accessEverything")};        List securityReferences = new ArrayList<>();        securityReferences.add(new SecurityReference("loginToken", authorizationScopes));        return securityReferences;    }}

配置类定义了项目的基本信息，以及一个安全方案，设置了一个loginToken的请求头参数。

注意我这里指定了dev环境时使用，生产时就不需要这玩意了，省的消耗性能。

也可以在application.yml文件中加入以下代码的方式禁用生产环境时使用knife4j。

knife4j:  production: false #生产环境设为true关闭swagger

3.拦截器配置

若你的项目有配置拦截器，那么可能也会拦截knife4j的一些请求地址，需要解除拦截文档地址，示例如下。

@Configuration@ComponentScan(basePackages = {"com.huangtl.app.controller"})public class WebApplicationConfig implements WebMvcConfigurer {    @Bean    public AppInterceptor appInterceptor() {        return new AppInterceptor(); //自定义拦截器    }    @Override    public void addInterceptors(InterceptorRegistry registry) {        registry.addInterceptor(appInterceptor()).addPathPatterns("/**").excludePathPatterns("/config/**")                .excludePathPatterns("/swagger-resources/**", "/swagger-ui.html", "/error","/doc.html","/v2/api-docs/**","/v2/api-docs-ext/**");    }}

4.浏览器界面

项目启动后浏览器打开http://localhost:8080/doc.html，当然ip和端口根据自己项目情况来。

knife4j界面

是不是比Swagger的界面好看呢？左侧展示了knife4j的几个自带菜单以及我们的接口菜单，接口菜单下是一个个接口的文档内容和调试的入口。

主页：显示项目的基本信息，各种请求方式的接口数量。

Authorize：显示我们定义的安全方案内容。

SwaggerModels：显示的是我们代码中定义的请求体。

文档管理：可以配置全局参数，比如请求表单参数和header参数；可以下载word/markdown/pdf等离线文档；可以选择knife4j提供的一些个性化特性。

我们来看看左侧菜单的 Authorize的菜单，这是因为我们在配置类里定义Docket时添加了.securitySchemes方法增加了安全方案，否则的话是没有该菜单的。

@Bean("测试平台")public Docket createRestApi() {    Predicate selector1 = RequestHandlerSelectors.basePackage("com.huangtl.app.controller");    return new Docket(DocumentationType.SWAGGER_2)            .groupName("测试平台")            .apiInfo(apiInfo())            .select()            .apis(Predicates.or(selector1))            .paths(PathSelectors.any())            .build()            .securityContexts(securityContext())            .securitySchemes(securitySchemes())            ;}

打开Authorize菜单会有一个我们在配置类里定义的key，我这里是配置了一个叫loginToken的header请求头，填写一个对应参数值，这样每个接口调试时会自动带上这个值。

Authorize菜单

点开左侧的某个接口菜单下的接口，左侧有文档和调试两个标签，调试部分可以选择请求头部和请求参数两部分，可以看到请求头部自动带出了我们在Authorize菜单配置的内容，我们来调试下请求时看是否会带上这个请求信息。

调试Authorize配置

点击发送调用接口，可以看到确实多了一个配置的请求头信息。

调试Authorize配置

以上就是使用knife4j的全部内容了，感兴趣的可以自己去官网了解更多内容。