自定义实现 Java17+SpringBoot3+OpenAPI+Knife4j Starter

文章目录

    • 前言
    • 正文
      • 1 创建starter项目
        • 1.1 依赖文件
        • 1.2 配置信息
      • 2 自定义starer代码开发
        • 2.1 配置字段的定义
        • 2.2 自动配置类
      • 3 验证starter
        • 3.1 测试项目的配置
        • 3.2 功能配置 application.yml
        • 3.3 测试代码
          • 3.3.1 实体类
          • 3.3.2 控制器1
          • 3.3.2 控制器2
      • 4 效果展示
        • 4.1 主页
        • 4.2 实体类列表
        • 4.3 自定义文档
        • 4.4 接口文档
    • 附录
      • 1 参考文档
      • 2 注意事项
        • 2.1 测试项目git地址
        • 2.2 starter项目目录

前言

一直以来,在接口文档这块没怎么尝试过比较新的技术点,使用的都是swagger2 和 低版本的 knife4j

本次就研究下在高版本的情况下,基于swagger的接口文档有什么变化。

本文基于以下环境:

组件版本
Java17
SpringBoot3.2.5
knife4j-openapi3-jakarta-spring-boot-starter4.5.0

正文

1 创建starter项目

创建一个Maven类型的SpringBoot项目,作为starter组件的开发。

1.1 依赖文件

Maven项目中,使用pom.xml文件来管理依赖。这里列举以下在starter项目中,使用到的依赖坐标。
此处指定了Java版本、Maven编译Java代码时使用的Java版本,并切设置项目的编码格式为UTF-8格式。

<properties><java.version>17</java.version><maven.compiler.source>17</maven.compiler.source><maven.compiler.target>17</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding><spring-boot.version>3.2.5</spring-boot.version><knife4j-openapi3-jakarta-version>4.5.0</knife4j-openapi3-jakarta-version>
</properties>
<dependencies>
<!-- https://www.mvncenter.com/search/org.springframework.boot/spring-boot-starter-->
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter</artifactId>
</dependency><!-- https://www.mvncenter.com/search/com.github.xiaoymin/knife4j-openapi3-jakarta-spring-boot-starter-->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>${knife4j-openapi3-jakarta-version}</version>
</dependency><dependency><groupId>jakarta.servlet</groupId><artifactId>jakarta.servlet-api</artifactId>
</dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-autoconfigure</artifactId>
</dependency>
<dependency><groupId>org.springframework</groupId><artifactId>spring-webmvc</artifactId>
</dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-configuration-processor</artifactId><optional>true</optional><scope>compile</scope>
</dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional>
</dependency>
</dependencies><dependencyManagement><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-dependencies</artifactId><version>${spring-boot.version}</version><type>pom</type><scope>import</scope></dependency></dependencies>
</dependencyManagement>
1.2 配置信息

因为这个starter组件是基于SpringBoot3.x开发的,所以在自定义starter时,使用新的写法,不在直接使用spring.factories文件对自动配置类进行配置。

resources目录下,创建目录 META-INF/spring,然后创建名为org.springframework.boot.autoconfigure.AutoConfiguration.imports的文件备用。

2 自定义starer代码开发

自定义starter的开发,代码量不多,主要是一个自动配置类和配置字段的定义。

2.1 配置字段的定义
package org.feng.basic.swagger.properties;import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;/*** Swagger 配置属性** @author feng*/
@Data
@ConfigurationProperties(prefix = SwaggerProperties.PREFIX)
public class SwaggerProperties {public static final String PREFIX = "swagger.config";private String title;private String version;private String description;private String termsOfService;private String licenseName;private String licenseUrl;private Contact contact;@Datapublic static class Contact {private String name;private String url;private String email;}
}
2.2 自动配置类

使用注解 ConditionalOnProperty 来指定是否进行配置bean的加载。

主要条件是 knife4j.enable=true,当满足条件时,配置类中的内容生效。

除此之外,在文件org.springframework.boot.autoconfigure.AutoConfiguration.imports 中,添加自动配置类的全名(包名+类名)。
比如,我项目中的自动配置类会配置为:org.feng.basic.swagger.SwaggerAutoConfiguration

package org.feng.basic.swagger;import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.feng.basic.swagger.properties.SwaggerProperties;
import org.springdoc.core.customizers.GlobalOpenApiCustomizer;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.ThreadLocalRandom;/*** swagger自动配置类** @author feng*/
@ConditionalOnProperty(prefix = "knife4j", name = "enable", havingValue = SwaggerAutoConfiguration.TRUE, matchIfMissing = true)
@EnableConfigurationProperties(SwaggerProperties.class)
public class SwaggerAutoConfiguration {public static final String TRUE = "true";private final SwaggerProperties swaggerProperties;public SwaggerAutoConfiguration(@Autowired SwaggerProperties swaggerProperties) {this.swaggerProperties = swaggerProperties;}/*** 根据@Tag 上的排序,写入x-order** @return the global open api customizer*/@Beanpublic GlobalOpenApiCustomizer orderGlobalOpenApiCustomizer() {return openApi -> {
//            if (openApi.getTags() != null) {
//                openApi.getTags().forEach(tag -> {
//                    Map<String, Object> map = new HashMap<>();
//                    map.put("x-order", ThreadLocalRandom.current().nextInt(0, 100));
//                    tag.setExtensions(map);
//                });
//            }
//            if (openApi.getPaths() != null) {
//                openApi.addExtension("x-test123", "333");
//                openApi.getPaths().addExtension("x-abb", ThreadLocalRandom.current().nextInt(0, 100));
//            }};}@Beanpublic OpenAPI openApi() {return new OpenAPI().info(new Info().title(swaggerProperties.getTitle()).description(swaggerProperties.getDescription()).version(swaggerProperties.getVersion()).termsOfService(swaggerProperties.getTermsOfService()).contact(new Contact().name(swaggerProperties.getContact().getName()).url(swaggerProperties.getContact().getUrl()).email(swaggerProperties.getContact().getEmail())).license(new License().name(swaggerProperties.getLicenseName()).url(swaggerProperties.getLicenseUrl())));}
}

3 验证starter

在本地开发时,将 starter 项目进行 mvn install打包并上传jar到本地的maven仓库中。

随后,创建一个新项目,在新项目中使用刚刚写好的starter组件。起始就是引入它的maven坐标,这里的版本选择和starter保持一致。

3.1 测试项目的配置

在测试项目中,使用spring-boot-web组件。具体的pom.xml配置如下:

    <properties><java.version>17</java.version><maven.compiler.source>17</maven.compiler.source><maven.compiler.target>17</maven.compiler.target><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding><spring-boot.version>3.2.5</spring-boot.version></properties><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.feng</groupId><artifactId>spring-boot-swagger-starter</artifactId><version>0.0.1-SNAPSHOT</version></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency></dependencies><dependencyManagement><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-dependencies</artifactId><version>${spring-boot.version}</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement><build><plugins><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.8.1</version><configuration><source>17</source><target>17</target><encoding>UTF-8</encoding></configuration></plugin><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId><version>${spring-boot.version}</version><configuration><mainClass>org.feng.SpringBootSwaggerStarterTestApplication</mainClass><skip>true</skip></configuration><executions><execution><id>repackage</id><goals><goal>repackage</goal></goals></execution></executions></plugin></plugins></build>
3.2 功能配置 application.yml
server:port: 17813servlet:context-path: /
spring:servlet:multipart:max-file-size: 100MBmax-request-size: 100MBapplication:name: knife4j-spring-boot3-demo
springdoc:swagger-ui:path: /swagger-ui.htmltags-sorter: alpha#operations-sorter: orderapi-docs:path: /v3/api-docs# 分组配置,对不同的包进行分组group-configs:- group: 'test1'display-name: '测试1'paths-to-match: '/**'packages-to-scan: org.feng.test1.controller- group: 'test2'display-name: '测试2'paths-to-match: '/**'packages-to-scan: org.feng.test2.controllerdefault-flat-param-object: trueknife4j:enable: truesetting:language: zh_cnswagger-model-name: 实体类列表# 是否在每个Debug调试栏后显示刷新变量按钮,默认不显示enableReloadCacheParameter: true# 是否开启界面中对某接口的版本控制,如果开启,后端变化后Ui界面会存在小蓝点enableVersion: true# 针对RequestMapping的接口请求类型,在不指定参数类型的情况下,如果不过滤,默认会显示7个类型的接口地址参数,如果开启此配置,默认展示一个Post类型的接口地址enableFilterMultipartApis: true# 是否开启动态参数调试功能enableDynamicParameter: true# 是否显示FooterenableFooter: falseenableFooterCustom: truefooterCustomContent: Apache License xx | Copyright  xxxx [xxxx-xxxx](https://xxxx.com/xxxx)# 自定义主页enable-home-custom: falsehome-custom-path: classpath:markdown/README.mddocuments:- name: 自定义文档1locations: classpath:markdown/*group: 测试1- name: 自定义文档2locations: classpath:markdown1/*group: 测试2# 启用简单的权限管理,访问接口文档需要登录basic:enable: trueusername: abcpassword: 123# http://www.knife4j.net/insight:enable: falseservice-name: boot3secret: S6CsnS8AnPVyb8vvChcdXm4R3p6A6KlAISxBg3IIEgk=server: http://localhost:10086namespace: spring3swagger:config:title: '${spring.application.name}的在线文档'description: '在线文档'version: 'v1'terms-of-service: ''contact:name: 'feng'email: 'fengsoshuai@163.com'url: ''license-name: ''license-url: ''
3.3 测试代码
3.3.1 实体类
package org.feng.model;import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;import java.io.Serial;
import java.io.Serializable;
import java.time.LocalDateTime;/*** TODO** @author feng*/
@Data
public class User implements Serializable {@Serialprivate static final long serialVersionUID = 7250829747040287299L;@Schema(title = "userId", description = "用户ID", defaultValue = "1")private Long id;@Schema(description = "名称", requiredMode = Schema.RequiredMode.REQUIRED)private String name;@Schema(description = "注册日期")private LocalDateTime registerDate;
}
3.3.2 控制器1
package org.feng.test1.controller;import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.feng.model.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;/*** TODO** @author feng*/
@Tag(name = "test1")
@RestController
@RequestMapping("/test1")
public class Test1Controller {@Operation(summary = "获取详情")@GetMapping("/getOneById")public User getOneDetailById(@RequestParam(required = false) Integer id) {return null;}
}
3.3.2 控制器2
package org.feng.test2.controller;import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.feng.model.User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;/*** TODO** @author feng*/
@Tag(name = "test2")
@RestController
@RequestMapping("/test2")
public class Test2Controller {@Operation(summary = "获取详情")@GetMapping("/getOneById")public User getOneDetailById(@RequestParam(required = false) Integer id) {return null;}
}

4 效果展示

启动项目后,访问链接:http://localhost:17813/doc.html#/home

4.1 主页

在这里插入图片描述

4.2 实体类列表

在这里插入图片描述

4.3 自定义文档

在这里插入图片描述

4.4 接口文档

在这里插入图片描述

附录

1 参考文档

  • https://doc.xiaominfo.com/docs/quick-start#spring-boot-3
  • https://www.mvncenter.com/search/com.github.xiaoymin/knife4j-openapi3-jakarta-spring-boot-starter
  • https://www.mvncenter.com/search/org.springframework.boot/spring-boot-starter
  • https://gitee.com/xiaoym/swagger-bootstrap-ui-demo/tree/master/knife4j-spring-boot3-demo
  • http://www.knife4j.net/

2 注意事项

2.1 测试项目git地址

https://gitee.com/fengsoshuai/spring-boot-swagger-starter-test

注意:因为starter的代码和配置很少,就不单独建立仓库了。仓库只包含测试项目的代码。starter的代码和配置可以从本文中粘贴出来。

2.2 starter项目目录

在这里插入图片描述

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.hqwc.cn/news/692291.html

如若内容造成侵权/违法违规/事实不符,请联系编程知识网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

1.1. 离散时间鞅-条件期望

1.1. 离散时间鞅-条件期望 条件期望1. 条件期望的定义1.1. 条件期望的定义1.2. 条件期望的存在唯一性 2. 条件期望的示例2.1. X ∈ F X \in \mathcal{F} X∈F&#xff0c; X X X与 F \mathcal{F} F独立的情形2.2. X X X是有限 σ \sigma σ代数情形2.3. X X X是随机变量生成…

Spring高手之路18——从XML配置角度理解Spring AOP

文章目录 1. Spring AOP与动态代理1.1 Spring AOP和动态代理的关系1.2 AOP基本术语 2. 通过XML配置实现Spring AOP2.1 添加Spring依赖2.2 定义业务接口和实现类2.3 定义切面类2.4 配置XML 1. Spring AOP与动态代理 1.1 Spring AOP和动态代理的关系 Spring AOP使用动态代理作为…

Mysql 日志(redolog, binlog, undoLog)

重做日志-redolog 是什么 innoDB存储引擎层面的日志&#xff0c;它的作用是当 数据更新过程中数据库发生异常导致提交的记录丢失 为什么 mysql的基本存储结构是页&#xff08;记录都在页里面&#xff09;&#xff0c;所以更新语句时&#xff0c;mysql需要先把要更新的语句找…

【python】python淘宝交易数据分析可视化(源码+数据集)

&#x1f449;博__主&#x1f448;&#xff1a;米码收割机 &#x1f449;技__能&#x1f448;&#xff1a;C/Python语言 &#x1f449;公众号&#x1f448;&#xff1a;测试开发自动化【获取源码商业合作】 &#x1f449;荣__誉&#x1f448;&#xff1a;阿里云博客专家博主、5…

Linux下安装JDK并配置环境变量

一、Oracle官网下载jdk 1、官网地址 https://www.oracle.com/java/technologies/downloads/#java17 2、命令下载 wget https://download.oracle.com/java/17/latest/jdk-17_linux-x64_bin.tar.gz 3、解压 tar -zxvf jdk-17_linux-x64_bin.tar.gz 4、配置环境变量 ec…

企业OA办公系统开发笔记:1、搭建后端环境

文章目录 企业办公系统&#xff1a;搭建环境一、项目介绍1、介绍2、技术栈3、项目模块4、数据库 二、搭建环境1、搭建后端1.1、搭建父工程clfwzx-oa-parent1.2、搭建工具类父模块common1.3、搭建工具类common的子模块1.4、搭建实体类模块model和项目模块service-oa 2、配置依赖…

精选多个炫酷的数据可视化大屏(含源码),拿走就用~

末尾有链接 演示地址&#xff1a;可视化大数据展示中心 (null.fit) 可视化大数据展示模板-科技语者 (chgskj.cn)

AttributeError: module ‘PIL.Image‘ has no attribute ‘ANTIALIAS‘

问题描述 修改图片大小的时候&#xff0c;代码报错&#xff1a;AttributeError: module PIL.Image has no attribute ANTIALIAS 解决方案 在pillow的10.0.0版本中&#xff0c;ANTIALIAS方法被删除了。 方法1&#xff1a;修改版本&#xff08;不推荐&#xff09; pip instal…

【busybox记录】【shell指令】ls

目录 内容来源&#xff1a; 【GUN】【ls】指令介绍 【busybox】【ls】指令介绍 【linux】【ls】指令介绍 使用示例-默认输出&#xff1a; 列出目录内容 - 默认输出 列出目录内容 - 不忽略以.开头的文件 列出目录内容 - 不忽略以.开头的文件&#xff0c;只忽略.和..文件…

Linux i2c工具——i2c_tools

1 简介 i2c-tools是一个用于处理I2C&#xff08;Inter-Integrated Circuit&#xff09;总线的工具集&#xff0c;它在Linux环境中广泛使用。这个工具集包含了一系列命令行工具&#xff0c;用于在I2C总线上执行各种操作&#xff0c;例如扫描设备、读取/写入寄存器、检测设备等。…

electron进程间通信

Electron 应用程序的结构非常相似。 作为应用开发者&#xff0c;你将控制两种类型的进程&#xff1a;主进程 和 渲染器进程。 这类似于上文所述的 Chrome 的浏览器和渲染器进程。 主进程 每个 Electron 应用都有一个单一的主进程&#xff0c;作为应用程序的入口点。 主进程在 N…