胖虎的工具箱-编程导航 胖虎的工具箱-编程导航

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

2年前 (2022) 程序员胖胖胖虎阿
363 0 0

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

简介

说明

        本文用示例介绍knife4j的用法。（SpringBoot整合knife4j）

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

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

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

官网

首页：knife4j
文档：knife4j
gitee地址：https://gitee.com/xiaoym/knife4j

实例

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

依赖及配置

依赖

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

本处我使用比较新的版本展示。（目前2.0.9是最新的发布版，最稳定。）

版本的区别如下：

版本

说明

1.9.6

蓝色皮肤风格,开始更名，增加更多后端模块

2.0~2.0.5

Ui重写，底层依赖的springfox框架版本是2.9.2

2.0.6~

底层springfox框架版本升级至2.10.5，OpenAPI规范是v2

3.0~

底层依赖springfox框架版本升级至3.0.3，OpenAPI规范是v3

Knife4j配置（非必要）

配置方案：使用openApi3.0

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

package com.example.demo.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.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableOpenApi
// @EnableKnife4j
// @EnableSwagger2
public class Knife4jConfig {
    @Bean
    public Docket docket() {
        Docket docket = new Docket(DocumentationType.OAS_30)
                .apiInfo(new ApiInfoBuilder()
                        .title("我的标题")
                        .description("我的描述")
                        // .termsOfServiceUrl("http://www.xx.com/")
                        .contact(new Contact("knife", "https://knife.blog.csdn.net/", "xx@qq.com"))
                        .version("1.0")
                        .build())
                // 分组名称
                .groupName("all")
                .select()
                // 这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();

        return docket;
    }
}

其他配置方案：使用swagger2

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;
    }
}

代码

Controller

package com.example.demo.business.user.controller;

import com.example.demo.business.user.request.UserAddRequest;
import com.example.demo.business.user.request.UserEditRequest;
import com.example.demo.business.user.request.UserQueryRequest;
import com.example.demo.business.user.vo.UserVO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.BeanUtils;
import org.springframework.web.bind.annotation.*;

import javax.validation.Valid;
import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.List;

@Api(tags = "用户")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation("添加")
    @PostMapping("/add")
    public UserVO add(@RequestBody @Valid UserAddRequest userAddRequest) {
        // 将数据写到数据库
        UserVO userVO = new UserVO();
        BeanUtils.copyProperties(userAddRequest, userVO);
        userVO.setId(1L);
        userVO.setCreateTime(LocalDateTime.now());
        userVO.setUpdateTime(LocalDateTime.now());
        return userVO;
    }

    @ApiOperation("修改")
    @PostMapping("/edit")
    public UserVO edit(@RequestBody @Valid UserEditRequest userEditRequest) {
        // 修改数据库的数据
        UserVO userVO = new UserVO();
        BeanUtils.copyProperties(userEditRequest, userVO);
        userVO.setUpdateTime(LocalDateTime.now());
        return userVO;
    }

    @ApiOperation("查找")
    @GetMapping("/find")
    public List<UserVO> find(UserQueryRequest userQueryRequest) {
        return new ArrayList<>();
    }

    @ApiOperation("删除")
    @PostMapping("/delete")
    public void delete(Long id) {
        // 将数据库数据删除
    }
}

Entity

说明

        本处我将增删改查都单独写一个实体类。

        当然，也可以将增删改的参数都写到一个实体里边，通过@Null，@NotNull以及它们的groups属性来指定属于哪个分组。这样写在运行时不会有问题，但在Knife4j页面显示时会不正常，原因是：Swagger没有很好地处理好这种情况。

添加

package com.example.demo.business.user.request;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import javax.validation.constraints.NotBlank;

@Data
@ApiModel("添加用户")
public class UserAddRequest {
    @ApiModelProperty(value = "用户名", required = true)
    @NotBlank(message = "用户名不能为空")
    private String userName;

    @ApiModelProperty("昵称")
    private String nickName;

    @ApiModelProperty("邮箱")
    private String email;
}

修改

package com.example.demo.business.user.request;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;

@Data
@ApiModel("修改用户")
public class UserEditRequest {
    @ApiModelProperty(value = "用户ID", required = true)
    @NotNull(message = "用户ID不能为空")
    private Long id;

    @ApiModelProperty(value = "用户名", required = true)
    @NotBlank(message = "用户名不能为空")
    private String userName;

    @ApiModelProperty("昵称")
    private String nickName;

    @ApiModelProperty("邮箱")
    private String email;
}

查询

package com.example.demo.business.user.request;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import org.springframework.format.annotation.DateTimeFormat;

import java.time.LocalDateTime;

@Data
@ApiModel(value = "用户实体", description = "用户description")
public class UserQueryRequest {

    @ApiModelProperty("用户id")
    private Long id;

    @ApiModelProperty("用户名")
    private String userName;

    @ApiModelProperty("昵称")
    private String nickName;

    @ApiModelProperty("邮箱")
    private String email;

    @ApiModelProperty("创建时间")
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime createTime;

    @ApiModelProperty("修改时间")
    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime updateTime;
}

VO

package com.example.demo.business.user.vo;

import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.time.LocalDateTime;

@Data
@ApiModel(value = "用户实体", description = "用户description")
public class UserVO {

    @ApiModelProperty("用户id")
    private Long id;

    @ApiModelProperty("用户名")
    private String userName;

    @ApiModelProperty("昵称")
    private String nickName;

    @ApiModelProperty("邮箱")
    private String email;

    @ApiModelProperty(value = "创建时间")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime createTime;

    @ApiModelProperty(value = "修改时间")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime updateTime;

    @ApiModelProperty("删除标记。0：未删除 其他：已删除")
    private Long deletedFlag;
}

测试

knife4j跟Tomcat共用一个端口，默认Tomcat是8080。访问地址：

http://localhost:8080/doc.html

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

分组Url

“分组Url”是文档地址，其他软件（比如apifox）可以将它作为导入文档的url。

此网址可以直接访问：http://localhost:8080/v3/api-docs?group=all

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

文档

本处展示添加用户接口的文档：

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

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

自测

本处展示添加用户的自测方法

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

测试结果

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;
    }
}

清缓存

简介

        有时候Knife4j会出现莫名其妙的问题，比如：Knife4j页面的显示与后端的接口不一致。这是Knife4j的前端页面的缓存导致的。

        Knife4j的缓存全部存储在浏览器中的IndexedDB中，所以通过浏览器的强制刷新等操作是无法起到清理缓存的作用的。

官网

3.14 清除缓存 | knife4j

解决方案

F12=> Application=> Storage=> IndexdDB=> 清除Knife4j的缓存

方法如下图所示

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

清除之后 

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

其他网址

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

版权声明：程序员胖胖胖虎阿 发表于 2022年10月10日 上午12:00。
转载请注明：Knife4j--使用/教程/实例/配置 | 胖虎的工具箱-编程导航

相关文章

IDEA全新破解图文教程(IDEA最新破解教程,全年更新)
程序员胖胖胖虎阿
182
IntelliJ IDEA2020破解版(Intellij IDEA2022.1永久激活码永久有效)
程序员胖胖胖虎阿
192
条件变量 Cond
程序员胖胖胖虎阿
289
带你玩转“超大杯”ECS特性及实验踩坑【华为云至简致远】
程序员胖胖胖虎阿
472
关于SQL优化的21个小方法，你get了吗？
程序员胖胖胖虎阿
147
IntelliJ IDEA永久破解码(Intellij IDEA2019破解码亲测有效!!)
程序员胖胖胖虎阿
125

暂无评论

暂无评论...
致力于称为最好的程序员导航网站

友链申请 免责声明 关于我们

Copyright © 2022  胖虎的工具箱-编程导航   陇ICP备2022001249号