SpringBoot项目整合Knife4J

SpringBoot项目整合Knife4J

前言

为什么要使用API文档

首先我们要明白我们为什么要去使用API文档 ,在前后端脱离 开发的情况下,前端程序员无法实时的知道后端接口开发的进度,后端程序员总不能每开发完一个接口或者更新一次接口就去wx上去跟前端程序员说,嘿!哥们哥们,我新增了一个接口,这个接口是这样这样子...这样沟通的成本也太高了,而且有时候还说不明白,搞得双方都很难受😢,在这样的情况下,API文档应运而生。

什么是API文档

API 文档 是开发者了解 API 功能和如何正确使用的主要来源。它提供了详细的指导,包括请求格式、参数说明、响应结构等,API 文档的重要性在于它作为应用程序编程接口的纲要,为开发者提供了关键的信息,帮助他们正确、高效地使用和集成特定的 API。

Knife4j

官方文档:https://doc.xiaominfo.com/docs/quick-start

开源地址:https://gitee.com/xiaoym/knife4j

我们来简单介绍一下Knife4j。knife4j 是为Java MVC 框架集成Swagger 生成Api文档的增强解决方案,前身是swagger-bootstrap-ui ,取名knife4j是希望她能像一把匕首一样小巧 ,轻量 ,并且功能强悍!

knife4j的前身是swagger-bootstrap-ui ,为了契合微服务的架构发展,由于原来swagger-bootstrap-ui采用的是后端Java代码+前端Ui混合打包的方式,在微服务架构下显的很臃肿,因此项目正式更名为knife4j。

Knife4j的进化史

Knife4j从开源至今,目前主要经历版本的变化,分别如下:

版本 说明
1.0~1.9.6 名称是叫swagger-bootstrap-ui,蓝色风格Ui
1.9.6 蓝色皮肤风格,开始更名,增加更多后端模块
2.0~2.0.5 Ui基于Vue2.0+AntdV重写,黑色风格,参考示例,底层依赖的springfox框架版本是2.9.2,仅提供Swagger2规范的适配
2.0.6~2.0.9 底层springfox框架版本升级至2.10.5,仅提供Swagger2规范的适配
3.0~3.0.3 底层依赖springfox框架版本升级至3.0.3,OpenAPI规范是v3,过度版本,建议开发者不要使用
4.0~ 区分OpenAPI2和Swagger3的Maven坐标artifactId OpenAPI2规范服务端解析框架稳定在springfox2.10.5 OpenAPI3框架服务端解析跟随springdoc项目更新迭代

Swagger和Knife4J的关系

博主在刚接触Knife4j 的时候觉得这和Swagger没什么区别嘛,都是API规范文档的框架,在查阅了部分资料后,知道了他们两个直接的联系。

Knife4j是Swagger-UI的增强版,它是在Swagger-UI 的基础上进行了改进和优化 ,提供了更加完善 的交互体验和更加美观 的UI设计。同时,它也提供了更多的扩展功能,例如在线调试和多语言支持等。

其实看完Knife4j官方文档的介绍后也差不多知道Knife4j是Swagger的升级版

名称 开发语言&框架 状态 最后版本 风格
Knife4j Java、JavaScript、Vue 持续更新 黑色
swagger-bootstrap-ui Java、JavaScript、jQuery 停更 1.9.6 蓝色

SpringBoot整合Knife4j

okk,接下来进行我们的正题,SpringBoot项目如何接入Knife4j。

版本适配

但是在这之前我们要清楚Knife4j与SpringBoot版本之间的关系。

Spring Boot版本 Knife4j Swagger2规范 Knife4j OpenAPI3规范
1.5.x~2.0.0 <Knife4j 2.0.0 >=Knife4j 4.0.0
2.0~2.2 Knife4j 2.0.0 ~ 2.0.6 >=Knife4j 4.0.0
2.2.x~2.4.0 Knife4j 2.0.6 ~ 2.0.9 >=Knife4j 4.0.0
2.4.0~2.7.x >=Knife4j 4.0.0 >=Knife4j 4.0.0
>= 3.0 >=Knife4j 4.0.0 >=Knife4j 4.0.0

由于目前绝大部分项目使用的还是JDK8,Knife4j OpenAPI3 需要JDK版本在17 及以上,所以我们就不作介绍。我们这块介绍的是SpringBoot版本在2.4.0~2.7.x ,Knife4j版本在 >= 4.0.0,使用Knife4j要注意版本的问题。

实现步骤

1.导入依赖

自4.0版本开始,maven组件的artifactId已经发生了变化。

xml 复制代码
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>{maven仓库最新版本}</version>
</dependency>

在4.0版本之前,maven坐标如下:

xml 复制代码
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>{<4.0.0版本}</version>
</dependency>

2.编写配置类

给大家看一下我的项目架构,在Knife4jConfig下编写配置类。

java 复制代码
/**
 * Knife4j配置类
 */
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        // 网站标题
                        .title("向阳的Swagger文档")
                        // 描述 可以穿插md语法
                        .description("# 这是描述!")
                        // 服务条款
                        .termsOfServiceUrl("......")
                        // 设置作者 服务器url 邮箱
                        .contact(new Contact("向阳", "http://localhost:9999/demo", "xxx"))
                        // 许可证
                        .license("...")
                        // 许可证url
                        .licenseUrl("....")
                        // 版本
                        .version("1.0")
                        .build())
                .groupName("test测试组")
                .select()
                // 要扫描的包
                .apis(RequestHandlerSelectors.basePackage("com.shousi.knife4jdemo.controller"))
                // 要扫描的url
                .paths(PathSelectors.any())
                .build();
    }
}

新建一个controller进行测试

下面是我创建的一个测试接口,类命为TestController。

java 复制代码
@Api(tags = "测试模块")
@RestController
@RequestMapping("/test")
public class TestController {
    @GetMapping("/world")
    public String world(){
        return "world knife4j";
    }

    @ApiOperation(value = "打招呼")
    @GetMapping("/hello")
    @ApiImplicitParam(name = "name", value = "姓名", required = true)
    public String hello(@RequestParam("name") String name){
        return "hello" + name;
    }
}

启动项目

启动项目,访问http://localhost:端口号/doc.html 。即可进入API文档。

Knife4j增强配置

在yml配置文件中添加增强配置 ,在第一次进入API管理文档时需要填写账号、密码,防止网址泄露让外来人员进行破坏。

yml 复制代码
knife4j:
  enable: true
  # 开启Swagger的Basic认证功能,默认是false
  basic:
    enable: true
    # 用户名
    username: root
    # 密码
    password: 123456

同样可以设置productionfalse ,在生产环境下不开放Knife4j。

yml 复制代码
knife4j:
  production: false

常用注解

注解 解释 相关参数
@Api 对某个Controller进行详细描述 tags:该controller的名称
@ApiOperation 对某个接口/方法进行详细描述 value:该接口的详细名称/功能
@ApiImplicitParam 对某个接口/方法的单个参数进行详细描述 name:参数的名称 value:参数的描述 required:是否必填 dataType:参数类型
@ApiImplicitParams 对某个接口/方法的多个参数进行详细描述 name:参数的名称 value:参数的描述 required:是否必填 dataType:参数类型
@ApiModel 对某个实体类的基本信息进行描述 description:实体类的描述
@ApiModelProperty 对某个实体类的每个属性的进行详细描述 name:参数的名称 value:参数的描述 required:是否必填 dataType:参数类型

例子展示

实体类注解

当然也可以对实体类进行更详细的配置,例如设置dataType 属性类型、required 是否必须填写。

Controller注解

Knife4j文档导出

相信大家应该都使用过Apifox 这款API文档(如果没有使用过可以在评论区留言,下一期可以详细介绍一下),可以将项目的Knife4j文档 导入Apifox 当中,我们不再用去一步一步手搓文档

实现步骤

1.进入Apifox选择导入项目

2.选择Knife4j进行导入

注意!如果你添加了增强配置 ,需要填写yml配置文件 中对应的账户和密码,填写完毕后进行提交

导入项目

如果没有项目目录进行新建,如果有的话则选择已有的目录。

选择模块导入

如果是第一次导入的话,建议全部导入,如果需要筛选则自行选择。

发送请求

发送请求后,我们发现可以正常使用,这样就大功告成啦。

结语

正确的使用Knife4j 可以大大节省时间、开发成本,学会使用Knife4j还是十分重要的!有关于Knife4j的后续以及一些高级用法也会继续更新,希望大家可以多多关注。

------👦[作者]:向阳256
------⏳[更新]:2024.10.19
------🥰本人技术有限,如果有不对指正需要更改或者有更好的方法,欢迎到评论区留言。
相关推荐
2401_854391082 分钟前
Spring Boot框架下租房管理系统的设计与实现
数据库·spring boot·php
luoluoal5 分钟前
基于Spring Boot的装饰工程管理系统源码(springboot)
java·spring boot·后端
2401_857617626 分钟前
Spring Boot框架在中小企业设备管理中的创新应用
数据库·spring boot·后端
J不A秃V头A20 分钟前
IDEA实用小技巧:方法之间的优雅分割线
java·intellij-idea
Jonas2428 分钟前
Spring里边的设计模式
后端
涛涛6号31 分钟前
PageHelper(springboot,mybatis)
java·spring boot·后端
夜雨翦春韭42 分钟前
【代码随想录Day58】图论Part09
java·开发语言·数据结构·算法·leetcode·图论
豪宇刘1 小时前
Shiro回话管理和加密
java·后端·spring
V+zmm101341 小时前
警务辅助人员管理系统小程序ssm+论文源码调试讲解
java·小程序·毕业设计·mvc·课程设计·1024程序员节
Seven 7 Chihiro1 小时前
[进阶]java基础之集合(三)数据结构
java·开发语言