Springboot中整合knife4j接口文档的过程详解

目录
  • 什么是knife4j
  • 界面欣赏
    • 主页
    • 接口文档
    • 调试界面
    • 参数实体
  • 整合 knife4j
    • 引入 maven 依赖
    • knife4j 配置文件
    • 配置API接口
  • knife4j 常用特性
    • 全局参数
    • 离线文档

在项目开发过程中,web项目的前后端分离开发,APP开发,需要由前端后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发。

什么是knife4j

简单说knife4j就swagger的升级版API文档的一个框架,但是用起来比swagger方便多了,UI更加丰富。

界面欣赏

主页

接口文档

调试界面

参数实体

整合 knife4j

引入 maven 依赖

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用时请在maven中央仓库搜索3.X最新版本号-->
    <version>3.0.3</version>
</dependency>

knife4j 配置文件

创建 Knife4jConfig 文件

package com.didiplus.common.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.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
 * Author: didiplus
 * Email: 972479352@qq.com
 * CreateTime: 2022/4/25
 * Desc: knife4j 配置
 */
@Configuration
@EnableKnife4j
public class Knife4jConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.didiplus"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot项目 后台服务API接口文档")
                .description("使用 knife4j 搭建的后台服务API接口文档")
                .termsOfServiceUrl("http://localhost:8080/")
                .contact("didiplus")
                .version("1.0.0")
}

配置API接口

package com.didiplus.modules.sys.controller;
import com.didiplus.modules.sys.domain.SysDictType;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* Author: didiplus
* Email: 972479352@qq.com
* CreateTime: 2022/4/25
* Desc: 数据字典控制器
*/
@RestController
@Api(tags = "数据字典")
@RequestMapping("/api/sys/dictType")
public class SysDictTypeController {

    @ApiOperation("添加")
    @PostMapping("/add")
    public SysDictType add() {
        SysDictType dictType = new SysDictType();
        dictType.setId("1");
        dictType.setTypeName("用户状态");
        dictType.setTypeCode("user_type");
        dictType.setDescription("用户状态");
        dictType.setEnable("true");
        return  dictType;
    }

}

通过 @Api注解标注需要生成接口文档,通过 @ApiOperation注解标注接口名。 同时我们给 SysDictType也加上对应的注解

package com.didiplus.modules.sys.domain;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import javax.validation.constraints.NotEmpty;
/**
 * Author: didiplus
 * Email: 972479352@qq.com
 * CreateTime: 2022/4/25
 * Desc: 字典类型领域模型
 */
@Data
@ApiModel(value = "字典类型")
public class SysDictType {
    @ApiModelProperty("ID")
    private String id;
    @NotEmpty(message = "字典编码不能为空")
    @ApiModelProperty(name = "字典名称",example = "用户ID")
    private String typeName;
    @ApiModelProperty(value = "字典编码")
    private String typeCode;
    @ApiModelProperty(value = "字典描述")
    private String description;
    @NotEmpty(message = "字典状态不能为空")
    @ApiModelProperty(value = "字典状态")
    private String enable;
}

通过 @ApiModel标注这是一个参数实体,通过 @ApiModelProperty标注字段说明。
访问 http://localhost:8080/doc.html体验一下,出现访问资源异常

出现这个问题的原因是因为我们加上了 ResponseBodyAdvice统一处理返回值/响应体,导致给Swagger的返回值也包装了一层,UI页面无法解析。可以通过 http://localhost:8080/v2/api-docs?group=SwaggerDemo观察Swagger返回的json数据。

既然知道了问题原因那就很好解决了,我们只需要在ResponseBodyAdvice处理类中只转换我们自己项目的接口即可。

@RestControllerAdvice(basePackages = "com.didiplus.modules")
public class ResponseAdvice  implements ResponseBodyAdvice<Object> {
....省略....
}

详细的可以参考SpringBoot 如何统一后端返回格式。通过添加basePackage属性限定统一返回值的范围,这样就不影Swagger了 ,重启服务器再次访问swagger接口地址,就可以看到接口文档页面了。

knife4j 常用特性

knife4j 在 swagger 的基础上做了许多增强,这里介绍几个最常用的。使用增强特性需在application.yml 中开启 。

knife4j:
  production: false
  enable: true

全局参数

前后端分离开发中一般使用 token 作为请求参数进行身份与权限鉴定,有放在 query(表单)和 header(请求头)的,knife4j 对这两种都进行了支持,只需在侧边栏‘文档管理 -> 全局参数设置’中设置。

离线文档

有时我们需要一份离线文档可以随时随地进行查看,knife4j 支持导出四种格式( md、html、doc 、json)的离线文档,在侧边栏‘文档管理 -> 离线文档’中导出。

到此这篇关于Springboot中整合knife4j接口文档的文章就介绍到这了,更多相关Springboot整合knife4内容请搜索我们以前的文章或继续浏览下面的相关文章希望大家以后多多支持我们!

(0)

相关推荐

  • SpringBoot中整合knife4j接口文档的实践

    在项目开发中,web项目的前后端分离开发,APP开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护 接口文档使得项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发,项目维护中或者项目人员更迭,方便后期人员查看.维护 一.界面先赏 1.首页 2.接口文档 3.调试 二.整合 knife4j 1.引入 maven 依赖 <!-- knife4j接口文档 start --> <dependency> <group

  • Springboot2整合knife4j过程解析

    knife4j官网:https://doc.xiaominfo.com/guide/useful.html 这玩艺就swagger的升级版,但是用起来比swagger方便多了,至少不会出现莫名的版本兼容问题 下面记录一个配置示例 1.代码结构 2.pom.xml <?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0&

  • Springboot整合knife4j与shiro的操作

    一.介绍knife4j 增强版本的Swagger 前端UI,取名knife4j是希望她能像一把匕首一样小巧,轻量,并且功能强悍,更名也是希望把她做成一个为Swagger接口文档服务的通用性解决方案,不仅仅只是专注于前端Ui前端. 二.Spring Boot 整合knife4j 第一步 在Maven中的pom.xml文件引入: <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>kni

  • Java基础之SpringBoot整合knife4j

    插件的特点 1.非常简洁清爽的UI设计,接口的快速搜索. 2.支持个性化设置,个性化设置包含: 请求参数缓存 动态请求参数 RequestMapping接口过滤 HOST代理设置 3.全局参数设置,可以很方便的设置Token等权限认证参数. 4.离线API文档下载: Markdown(已支持) Html(已支持) Word(已支持) OpenApi(已支持) 5.对 json 格式的数据有更好的支持,可以折叠展开等. knife4j官方文档地址 : https://doc.xiaominfo.c

  • Springboot中整合knife4j接口文档的过程详解

    目录 什么是knife4j 界面欣赏 主页 接口文档 调试界面 参数实体 整合 knife4j 引入 maven 依赖 knife4j 配置文件 配置API接口 knife4j 常用特性 全局参数 离线文档 在项目开发过程中,web项目的前后端分离开发,APP开发,需要由前端后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发. 什么是knife4j 简单说knife4j就swagger的升级版API文档的一个框架,但是用起来比swagger方便多了,UI更加丰富. 界面欣赏

  • SpringBoot使用swagger生成api接口文档的方法详解

    目录 前言 具体例子 maven配置 项目application.yml配置 springApplication添加swagger注解 在控制层添加swagger注解 前言 在之前的文章中,使用mybatis-plus生成了对应的包,在此基础上,我们针对项目的api接口,添加swagger配置和注解,生成swagger接口文档 具体可以查看本站spring boot系列文章: spring boot项目使用mybatis-plus代码生成实例 具体例子 maven配置 在使用之前,我们需要添加s

  • SpringBoot中如何统一接口返回与全局异常处理详解

    目录 背景 统一接口返回 定义API返回码枚举类 定义正常响应的API统一返回体 定义异常响应的API统一返回体 编写包装返回结果的自定义注解 定义返回结果拦截器 WebMvc配置类拦截器注册者添加返回结果拦截器 编写响应体处理器 接口调用 测试结果 全局异常处理 编写自定义异常基类 编写自定义业务异常类 定义全局异常处理类 接口调用 测试结果 总结 背景 在分布式.微服务盛行的今天,绝大部分项目都采用的微服务框架,前后端分离方式.前端和后端进行交互,前端按照约定请求URL路径,并传入相关参数,

  • Spring Boot项目集成Knife4j接口文档的实例代码

    目录 1.在pom.xml引入依赖包 2.创建Knife4j配置文件 3.使用Knife4j注解 4.全局参数 Knife4j就相当于是swagger的升级版,对于我来说,它比swagger要好用得多 1.在pom.xml引入依赖包 <!-- Swagger配置依赖knife4j --> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>knife4j-spring-b

  • Python实现自动化处理Word文档的方法详解

    目录 1. 批量生成Word文档 2. 将Word文档批量转换成PDF 3. 在Word文档中批量标记关键词 4. 在Word文档中批量替换关键词 使用Python实现Word文档的自动化处理,包括批量生成Word文档.在Word文档中批量进行查找和替换.将Word文档批量转换成PDF等. 1. 批量生成Word文档 安装openpyxl模块 pip install openpyxl 安装python-docx模块 pip install python-docx openpyxl模块可以读写扩展

  • SpringBoot中dubbo+zookeeper实现分布式开发的应用详解

    总体实现思路是启动一个生产者项目注册, 将所含服务注册到zookeeper的注册中心, 然后在启动一个消费者项目,将所需服务向zookeeper注册中心进行订阅, 等待注册中心的通知 注册中心基于负载均衡算法给消费者匹配到合适的生产者主机,然后通知消费者可以使用 实现生产者 导入zookeeper依赖包 <!-- Dubbo Spring Boot Starter --> <dependency> <groupId>org.apache.dubbo</groupI

  • Python操作word文档的示例详解

    目录 写在前面 创建一个文档 先实现第一步,写入一个标题 添加文字段落 列表的添加 图片的添加 表格添加 相关样式设置 页眉和页脚 写在前面 python-docx 不支持 doc 文档,一定要注意该点,如果使用 doc 文档,需要提前将其用 Word 相关软件转换为 docx 格式. doc 和 docx 是存在本质差异的,一个是二进制,另一个 XML 格式的文件. 模块的安装 pip install python-docx . 以下网址首先准备好 官方手册:https://python-do

  • 运用Python巧妙处理Word文档的方法详解

    目录 工具 生成Word案例 读取操作word文档 总结 工具 python3.7 Pycharm Excel python-docx 生成Word案例 创建一个demo.doc文档,代码如下: from docx import Document from docx.shared import Cm,Pt from docx.document import Document as Doc #构建doc对象 document = Document() #操作文档标题 document.add_he

  • Java生成word文档的示例详解

    目录 目标 依赖 模版 实体 代码 目标 依赖 <!-- poi工具类--> <dependency> <groupId>com.deepoove</groupId> <artifactId>poi-tl</artifactId> <version>1.12.0</version> </dependency> 模版 实体 实体类需要和模版内的动态字段对应 代码 @GetMapping(value =

随机推荐