企业官网建设流程全解析

先进网站建设有哪些,怎么找拉新推广平台,西海岸新区城市建设局公示网站,常德网站优化公司SpringBoot项目整合Knife4J 前言 为什么要使用API文档什么是API文档 Knife4j Knife4j的进化史Swagger和Knife4J的关系 SpringBoot整合Knife4j 版本适配实现步骤 1.导入依赖2.编写配置类新建一个controller进行测试启动项目 Knife4j增强配置常用注解 例子展示 实体类注解Co…SpringBoot项目整合Knife4J前言为什么要使用API文档什么是API文档Knife4jKnife4j的进化史Swagger和Knife4J的关系SpringBoot整合Knife4j版本适配实现步骤1.导入依赖2.编写配置类新建一个controller进行测试启动项目Knife4j增强配置常用注解例子展示实体类注解Controller注解Knife4j文档导出实现步骤1.进入Apifox选择导入项目2.选择Knife4j进行导入导入项目选择模块导入发送请求结语大家好我是向阳一个想成为优秀全栈开发工程师的有志青年今天我们来介绍在前后端脱离开发项目中我们会使用到的一款强大的API规范文档的框架——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,蓝色风格Ui1.9.6蓝色皮肤风格,开始更名增加更多后端模块2.0~2.0.5Ui基于Vue2.0AntdV重写,黑色风格,参考示例底层依赖的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坐标artifactIdOpenAPI2规范服务端解析框架稳定在springfox2.10.5OpenAPI3框架服务端解析跟随springdoc项目更新迭代Swagger和Knife4J的关系博主在刚接触Knife4j的时候觉得这和Swagger没什么区别嘛都是API规范文档的框架在查阅了部分资料后知道了他们两个直接的联系。Knife4j是Swagger-UI的增强版它是在Swagger-UI的基础上进行了改进和优化提供了更加完善的交互体验和更加美观的UI设计。同时它也提供了更多的扩展功能例如在线调试和多语言支持等。其实看完Knife4j官方文档的介绍后也差不多知道Knife4j是Swagger的升级版。名称开发语言框架状态最后版本风格Knife4jJava、JavaScript、Vue持续更新无黑色swagger-bootstrap-uiJava、JavaScript、jQuery停更1.9.6蓝色SpringBoot整合Knife4jokk接下来进行我们的正题SpringBoot项目如何接入Knife4j。版本适配但是在这之前我们要清楚Knife4j与SpringBoot版本之间的关系。Spring Boot版本Knife4j Swagger2规范Knife4j OpenAPI3规范1.5.x~2.0.0Knife4j 2.0.0Knife4j 4.0.02.0~2.2Knife4j 2.0.0 ~ 2.0.6Knife4j 4.0.02.2.x~2.4.0Knife4j 2.0.6 ~ 2.0.9Knife4j 4.0.02.4.0~2.7.xKnife4j 4.0.0Knife4j 4.0.0 3.0Knife4j 4.0.0Knife4j 4.0.0由于目前绝大部分项目使用的还是JDK8Knife4j OpenAPI3需要JDK版本在17及以上所以我们就不作介绍。我们这块介绍的是SpringBoot版本在2.4.0~2.7.xKnife4j版本在 4.0.0使用Knife4j要注意版本的问题。实现步骤1.导入依赖自4.0版本开始maven组件的artifactId已经发生了变化。dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-openapi2-spring-boot-starter/artifactId version{maven仓库最新版本}/version /dependency在4.0版本之前maven坐标如下dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-spring-boot-starter/artifactId version{4.0.0版本}/version /dependency2.编写配置类给大家看一下我的项目架构在Knife4jConfig下编写配置类。/** * 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。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管理文档时需要填写账号、密码防止网址泄露让外来人员进行破坏。knife4j: enable: true # 开启Swagger的Basic认证功能,默认是false basic: enable: true # 用户名 username: root # 密码 password: 123456同样可以设置production为false在生产环境下不开放Knife4j。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的后续以及一些高级用法也会继续更新希望大家可以多多关注。——??[作者] ——?[更新]2024.10.19 ——??本人技术有限如果有不对指正需要更改或者有更好的方法欢迎到评论区留言。