Knife4j--使用/教程/实例/配置

痛定思痛。 2022-09-15 15:59 450阅读 0赞

原文网址：[Knife4j--使用/教程/实例/配置\_IT利刃出鞘的博客-CSDN博客][Knife4j--_IT_-CSDN]

# 简介 #

**说明**

本文用实例介绍knife4j的使用。

knife4j是一个很好用的接口文档工具。之前用过swagger，觉得页面不太好，浏览技术网站时，偶然发现swagger-bootstrap-ui，能方便地将接口进行归类。

早期，swagger-boostrap-ui是1.x版本，如今swagger-bootsrap-ui到2.x，同时也更改名字knife4j，适用于单体和微服务项目。

knife4j跟swagger用法基本一样，swagger用法见：[Swagger--使用/教程/实例/配置\_IT利刃出鞘的博客-CSDN博客][Swagger--_IT_-CSDN]

**官网**

官网文档：[knife4j][]  
官网首页：[knife4j][knife4j 1]

# 实例 #

官网文档：[1.6 快速开始 | knife4j][1.6 _ _ knife4j]

## 依赖及配置 ##

**依赖**

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

**配置**

默认无需配置，引入包就可以直接用了。本处只是示例如果自定义一些东西该怎么写。

如果不配置此类，则用的是/v3/api-docs，若配置了本类，用的是/v2/api-docs

package com.example.demo.config;
    
    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.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @Configuration
    @EnableSwagger2
    public class Knife4jConfig {
        @Bean(value = "defaultApi2")
        public Docket defaultApi2() {
            Docket docket = new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(new ApiInfoBuilder()
                            .title("我的标题")
                            .description("我的描述")
                            // .termsOfServiceUrl("http://www.xx.com/")
                            .contact(new Contact("IT利刃出鞘", "https://knife.blog.csdn.net", "xx@qq.com"))
                            .version("1.0")
                            .build())
                    //分组名称
                    .groupName("all")
                    .select()
                    //指定Controller扫描路径。可以不具体到controller，它会扫描指定路径下的所有
                    .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                    .paths(PathSelectors.any())
                    .build();
            return docket;
        }
    }

## **代码** ##

跟swagger写法一样，见 ：[swagger--使用/教程/实例/配置\_IT利刃出鞘的博客-CSDN博客][Swagger--_IT_-CSDN]

## 测试 ##

knife4j跟Tomcat共用一个端口，默认Tomcat是8080，所以，这样访问即可：

[http://localhost:8080/doc.html][http_localhost_8080_doc.html]

![watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBASVTliKnliIPlh7rpnpg_size_20_color_FFFFFF_t_70_g_se_x_16][]

# 注意事项 #

## 全局响应的处理 ##

**其他网址**

[快速开始 | knife4j][_ knife4j]

若加了全局的响应的处理，则会报错，或者无法正常使用。比如：“Knife4j文档请求异常”。

解决方法：需要将knife4j的接口数据忽略掉，配置如下：

import com.fasterxml.jackson.core.JsonProcessingException;
    import com.fasterxml.jackson.databind.ObjectMapper;
    import org.example.common.entity.ResultWrapper;
    import org.springframework.core.MethodParameter;
    import org.springframework.http.MediaType;
    import org.springframework.http.converter.HttpMessageConverter;
    import org.springframework.http.server.ServerHttpRequest;
    import org.springframework.http.server.ServerHttpResponse;
    import org.springframework.util.AntPathMatcher;
    import org.springframework.web.bind.annotation.ControllerAdvice;
    import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;
     
    import java.util.Arrays;
    import java.util.List;
     
    @ControllerAdvice
    public class GlobalResponseBodyAdvice implements ResponseBodyAdvice<Object> {
        private List<String> KNIFE4J_URI = Arrays.asList(
                "/doc.html",
                "/swagger-resources",
                "/swagger-resources/configuration",
                "/v3/api-docs",
                "/v2/api-docs",
                "/webjars/**");
        @Override
        public boolean supports(MethodParameter returnType, 
    	                        Class<? extends HttpMessageConverter<?>> converterType) {
            // 若接口返回的类型本身就是ResultWrapper，则无需操作，返回false
            // return !returnType.getParameterType().equals(ResultWrapper.class);
            return true;
        }
     
        @Override
        public Object beforeBodyWrite(Object body, MethodParameter returnType, 
    	                              MediaType selectedContentType,
                                      Class<? extends HttpMessageConverter<?>> selectedConverterType,
                                      ServerHttpRequest request, ServerHttpResponse response) {
            if (body instanceof String) {
                // 若返回值为String类型，需要包装为String类型返回。否则会报错
                try {
                    ObjectMapper objectMapper = new ObjectMapper();
                    ResultWrapper<String> result = ResultWrapper.success().data(body);
                    return objectMapper.writeValueAsString(result);
                } catch (JsonProcessingException e) {
                    throw new RuntimeException("序列化String返回类型错误");
                }
            } else if (body instanceof ResultWrapper) {
                return body;
            } else if (isKnife4jUrl(request.getURI().getPath())) {
                //如果是接口文档的uri，直接跳过
                return body;
            }
            return ResultWrapper.success().data(body);
        }
     
     
        private boolean isKnife4jUrl(String uri) {
            AntPathMatcher pathMatcher = new AntPathMatcher();
            for (String s : KNIFE4J_URI) {
                if (pathMatcher.match(s, uri)) {
                    return true;
                }
            }
            return false;
        }
    }

# 其他网址 #

[Spring Boot 集成 Swagger-Bootstrap-UI，非常棒的解决方案][Spring Boot _ Swagger-Bootstrap-UI]

[Knife4j--_IT_-CSDN]: https://knife.blog.csdn.net/article/details/120753090
[Swagger--_IT_-CSDN]: https://knife.blog.csdn.net/article/details/120752619
[knife4j]: https://doc.xiaominfo.com/knife4j/documentation/
[knife4j 1]: https://doc.xiaominfo.com/
[1.6 _ _ knife4j]: https://doc.xiaominfo.com/knife4j/documentation/get_start.html
[http_localhost_8080_doc.html]: http://localhost:8080/doc.html
[watermark_type_ZHJvaWRzYW5zZmFsbGJhY2s_shadow_50_text_Q1NETiBASVTliKnliIPlh7rpnpg_size_20_color_FFFFFF_t_70_g_se_x_16]: /images/20220828/cc8f5ddf82b645c589c8940076031124.png
[_ knife4j]: https://doc.xiaominfo.com/guide/useful.html
[Spring Boot _ Swagger-Bootstrap-UI]: https://mp.weixin.qq.com/s/b3o8fYzcZgYIO39mU77sxQ