Spring Boot 3 整合 SpringDoc OpenAPI 生成接口文档

news2024/10/6 20:30:52

在这里插入图片描述

😄 19年之后由于某些原因断更了三年，23年重新扬帆起航，推出更多优质博文，希望大家多多支持～
🌷 古之立大事者，不惟有超世之才，亦必有坚忍不拔之志
🎐 个人CSND主页——Micro麦可乐的博客
🐥《Docker实操教程》专栏以最新的Centos版本为基础进行Docker实操教程，入门到实战
🌺《RabbitMQ》专栏主要介绍使用JAVA开发RabbitMQ的系列教程，从基础知识到项目实战
🌸《设计模式》专栏以实际的生活场景为案例进行讲解，让大家对设计模式有一个更清晰的理解
💕《Jenkins实战》专栏主要介绍Jenkins+Docker的实战教程，让你快速掌握项目CI/CD，是2024年最新的实战教程
🌞《Spring Boot》专栏主要介绍我们日常工作项目中经常应用到的功能以及技巧，代码样例完整
如果文章能够给大家带来一定的帮助！欢迎关注、评论互动～

Spring Boot整合 SpringDoc OpenAPI 生成接口文档

  • 1、前言
  • 2、SpringDoc OpenAPI版本介绍
  • 3、项目初始化
    • ❶ 配置依赖
    • ❷ 配置 Springdoc OpenAPI
    • ❸ 编写 REST Controller
    • ❹ 测试查看文档
  • 4、如何进行文档分组
  • 5、更换接口文档UI
  • 6、字段必填如何设置
  • 7、结语

1、前言

本文对应代码下载地址：https://download.csdn.net/download/lhmyy521125/89459959 无需积分！

在我们日常开发过程中，维护良好的 API 文档对于团队协作和开发效率至关重要。SpringDoc OpenAPI 是一个强大的工具，能够帮助我们轻松生成 OpenAPI 3.0 规范的文档，并提供交互式的 Swagger UI 界面。

在这里插入图片描述
本文跟着博主一起来学习如何在 Spring Boot 3 项目中整合 SpringDoc OpenAPI，生成在线接口文档

2、SpringDoc OpenAPI版本介绍

目前 SpringDoc OpenAPI 有两个版本 1.x 以及 2.x , 以下是版本对应的支持：

Springdoc OpenAPI 1.x：支持 JDK 8 及以上版本（Spring Boot 2.x and 1.x.）
Springdoc OpenAPI 2.x：最新版本要求 JDK 11 及以上（Spring Boot 3.x）

下表描述了两个版本主要模块的更改：

springdoc-openapi-v1springdoc-openapi-v2描述
springdoc-openapi-commonspringdoc-openapi-starter-common包含基础springdoc-openapi功能
springdoc-openapi-data-restspringdoc-openapi-starter-commonSpringData Rest 支持
springdoc-openapi-groovyspringdoc-openapi-starter-commonGroovy支持
springdoc-openapi-hateoasspringdoc-openapi-starter-commonSpring Hateoas 支持
springdoc-openapi-javadocspringdoc-openapi-starter-commonJavadoc支持
springdoc-openapi-kotlinspringdoc-openapi-starter-commonkotlin支持
springdoc-openapi-securityspringdoc-openapi-starter-commonSpring Security支持
springdoc-openapi-webmvc-corespringdoc-openapi-starter-webmvc-apiSpring WebMvc支持
springdoc-openapi-webflux-corespringdoc-openapi-starter-webflux-apiSpring WebFlux支持
springdoc-openapi-uispringdoc-openapi-starter-webmvc-ui在Spring WebMvc上下文中使用Swagger-UI
springdoc-openapi-webflux-uispringdoc-openapi-starter-webflux-ui在Spring WebFlux上下文中使用Swagger-UI

确保你使用的 JDK 版本与 springdoc-openapi 的版本相匹配。如果你使用的是 Spring Boot 3，Springdoc OpenAPI 2.x 是推荐的版本，因为 Spring Boot 3 也要求 JDK 17 及以上

3、项目初始化

❶ 配置依赖

创建一个新的 Spring Boot 3 项目，这里博主选用的JDK版本为JDK17 ，Spring Boot: 3.0.0，在我们的在 pom.xml 文件中添加 Springdoc OpenAPI 的依赖

	<dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- Springdoc OpenAPI Starter -->
   <dependency>
      <groupId>org.springdoc</groupId>
      <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
      <version>2.5.0</version>
   </dependency>

❷ 配置 Springdoc OpenAPI

springdoc-openapi 通过自动配置大多数情况下无需额外配置，但如果小伙伴有特定需求，可以在 application.yml 文件中添加配置，如：

springdoc:
  api-docs:
    enabled: true #
    path: /api-docs # 默认/v3/api-docs
  swagger-ui:
    path: /swagger-ui.html #自定义swagger-ui HTML文档路径

❸ 编写 REST Controller

创建一个简单的 REST 控制器，并使用 OpenAPI 注解来描述 API

定义User对象
首先，我们为 User 类的字段添加注解说明

/**
* description 字段描述
* example 字段返回示例
**/
@Data
public class User {
    @Schema(description = "用户ID", example = "1")
    private Long id;
    @Schema(description = "用户姓名", example = "张三")
    private String name;
    @Schema(description = "用户邮箱", example = "zhansan@qq.com")
    private String email;
}

创建一个简单的 REST Controller，并使用 OpenAPI 注解来描述 API

import com.toher.springdoc.bean.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.web.bind.annotation.*;

/**
 * @Author 麦可乐
 * @Date 2024/6/20 11:17 AM
 * @Version 1.0
 */

@RestController
@RequestMapping("/api/users")
public class UserController {

    @Operation(summary = "获取用户信息接口", description = "通过用户ID获取用户信息")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "用户信息",
                    content = {@Content(mediaType = "application/json",
                    schema = @Schema(implementation = User.class))}),
            @ApiResponse(responseCode = "404", description = "无法获取用户信息")
    })
    @GetMapping("/{id}")
    public User getUserById(@Parameter(description = "用户ID") @PathVariable Long id) {
        //模拟数据库获取用户
        User user = new User();
        user.setId(1L);
        user.setName("张三");
        user.setEmail("zhansan@qq.com");
        return user;
    }

    @Operation(summary = "创建用户接口", description = "创建一个新用户并返回带有用户id的User对象")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "用户创建",
                    content = {@Content(mediaType = "application/json",
                    schema = @Schema(implementation = User.class))})
    })
    @PostMapping
    public User createUser(@RequestBody User user) {
        //模拟数据库保存用户并返回用户ID主键
        user.setId(1L);
        return user;
    }
}

❹ 测试查看文档

最后启动项目访问查看文档 http://localhost:端口号/swagger-ui，小伙伴应该能够看到自动生成的 API 文档，并可以在界面中进行 API 测试，如下图：

在这里插入图片描述

4、如何进行文档分组

很多时候我们的接口很多，且可能不同的开发人员分配不同的模块，如果所有接口都集中在一起，很明显不利于我们查阅，这里博主介绍一下如何对文档进行分组。

需要实用一个配置 group-configs， 如博主的配置

springdoc:
  api-docs:
    enabled: true #
    path: /api-docs # 默认/v3/api-docs
  swagger-ui:
    path: /swagger-ui.html
  group-configs: #进行文档分组每个组配置对应的请求路径以及区分所在包
    - group: 'user'
      paths-to-match: '/api/users/**'
      packages-to-scan: com.toher.springdoc.user
    - group: 'product'
      paths-to-match: '/api/product/**'
      packages-to-scan: com.toher.springdoc.product

继续测试访问文档，右上角 Select a definition 查看是否已经分组
在这里插入图片描述

5、更换接口文档UI

相信很多小伙伴还是不喜欢swagger-ui的文档，这里博主介绍一个集 Swagger2 和 OpenAPI3 为一体的增强解决方案 - Knife4j

要使用 Knife4j 非常简单，只需要引入依赖即可

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

如果你希望开启 Knife4j 的增强，可以在yml配置文件中追加，具体Knife4j增强配置明细，可以查看官方文档 https://doc.xiaominfo.com/docs/features/enhance 这里就不赘述了

# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

重启我们的 SpringBoot 应用访问 http://localhost:端口号/doc.html 查看

在这里插入图片描述

6、字段必填如何设置

相信很多小伙伴在SpringBoot2的时候对于文档中一些字段的要求，如：必填，我们可以使用一个注解属性 required = true 来说明

	@Schema(description = "用户姓名", example = "张三" , required = true)
    private String name;

但实际上在最新版本的 Springdoc OpenAPI 中，@Schema 注解的 required 属性已经被标记为过时。取而代之的是将字段的非空校验放在参数或方法级别的注解上，结合 jakarta.validation

在 Springdoc OpenAPI 3 中，你可以使用 @Parameter 和 @RequestBody 注解来指定字段是否必需，同时在 @Schema 注解中可以通过指定非空属性

下面我们来改造一下我们之前的代码

User对象

import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotNull;
import lombok.Data;

@Data
public class User {
    @Schema(description = "用户ID", example = "1")
    private Long id;

    @Schema(description = "用户姓名", example = "张三")
    @NotNull(message = "Name必填")
    private String name;

    @Schema(description = "用户邮箱", example = "zhansan@qq.com")
    @NotNull(message = "Email必填")
    @Email(message = "邮箱格式不正确")
    private String email;
}

UserController

import com.toher.springdoc.user.bean.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.validation.Valid;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户接口")
public class UserController {

    @Operation(summary = "获取用户信息接口", description = "通过用户ID获取用户信息")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "用户信息",
                    content = {@Content(mediaType = "application/json",
                    schema = @Schema(implementation = User.class))}),
            @ApiResponse(responseCode = "404", description = "无法获取用户信息")
    })
    @GetMapping("/{id}")
    public User getUserById(@Parameter(description = "用户ID") @PathVariable Long id) {
        //模拟数据库获取用户
        User user = new User();
        user.setId(1L);
        user.setName("张三");
        user.setEmail("zhansan@qq.com");
        return user;
    }

    @Operation(summary = "创建用户接口", description = "创建一个新用户并返回带有用户id的User对象")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "用户创建",
                    content = {@Content(mediaType = "application/json",
                    schema = @Schema(implementation = User.class))})
    })
    @PostMapping
    public User createUser(@Valid @RequestBody User user) {
        //模拟数据库保存用户并返回用户ID主键
        user.setId(1L);
        return user;
    }
}

OK，我们还是重启应用观察文档说明。是否必填项上已经显示必填

在这里插入图片描述

7、结语

通过整合 Spring Boot 3 和 Springdoc OpenAPI，可以非常方便地生成交互式的在线 API 文档，帮助开发者和使用者理解和测试 API。这不仅提高了开发效率，还能保证文档的及时更新，保持与实际代码的一致性。

到这里相信小伙伴们已经能熟练在Spring Boot 3中生成接口文档了。如果本文对您有所帮助，希望 一键三连 给博主一点点鼓励，如果您有任何疑问或建议，请随时留言讨论！

在这里插入图片描述

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

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈，一经查实，立即删除！

相关文章

Go 内存模型与分配机制

Go 内存模型与分配机制

&#x1f49d;&#x1f49d;&#x1f49d;欢迎莅临我的博客&#xff0c;很高兴能够在这里和您见面&#xff01;希望您在这里可以感受到一份轻松愉快的氛围&#xff0c;不仅可以获得有趣的内容和知识&#xff0c;也可以畅所欲言、分享您的想法和见解。 推荐:「stormsha的主页」…
阅读更多...
亚马逊测评怎么赚钱，其他跨境电商平台也可以测评吗？

亚马逊测评怎么赚钱，其他跨境电商平台也可以测评吗？

跨境电商平台我们应该都知道&#xff0c;有Amazon&#xff08;亚马逊&#xff09;、eBay、全球速卖通&#xff08;AliExpress&#xff09;、Wish、Shopee、Lazada、阿里巴巴国际站、沃尔玛、敦煌、希音、temu、独立站等 近几年国内电商行业市场饱和&#xff0c;竞争大利润低&a…
阅读更多...
【机器学习】使用Python实现图神经网络（GNN）：图结构数据的分析与应用

【机器学习】使用Python实现图神经网络（GNN）：图结构数据的分析与应用

&#x1f525; 个人主页&#xff1a;空白诗 文章目录 一、引言二、图神经网络的基础知识1. 图的基本概念和术语2. 传统的图分析方法3. 图神经网络的基本原理4. GNN的基本模型 三、主要的图神经网络模型1. 图卷积网络&#xff08;Graph Convolutional Network, GCN&#xff09;2…
阅读更多...
“拥堵的6·18”一去不返，快递业终于“松了一口气”？

“拥堵的6·18”一去不返，快递业终于“松了一口气”？

一年一度的电商“618”大促已然步入尾声。 与往年不同的是&#xff0c;今年自4月起&#xff0c;天猫、京东、快手等主流平台相继官宣取消预售。自此&#xff0c;今年的“618”成了首个取消预售的大促节。只是&#xff0c;有的平台取消了“预售制”&#xff0c;却新增了“仅退款…
阅读更多...
巡检机器人智能联网，促进工厂自动化

巡检机器人智能联网，促进工厂自动化

随着工业4.0和智能制造的快速发展&#xff0c;企业引入自动化设备和智能机器人以提高生产效率和降低人工成本已成为大势所趋。其中&#xff0c;巡检机器人作为一种能够在复杂和危险环境中进行自动巡检的设备&#xff0c;受到了广泛关注。如何实现巡检机器人稳定、安全的联网是每…
阅读更多...
Nature将大罢工！或将致Nature创刊155年首次发生缺刊！

Nature将大罢工！或将致Nature创刊155年首次发生缺刊！

Nature要罢工了&#xff01; 这两天一则爆炸性新闻袭击了学术界&#xff0c;根据英国National Union of Journalists&#xff08;NUJ&#xff0c;全国记者工会&#xff09;发布的信息。Nature期刊的编辑们将于2024年6月20日起举行罢工。 而那一天正是Nature最新一期发布的日子…
阅读更多...
Wireshark v4 修改版安装教程（免费开源的网络嗅探抓包工具）

Wireshark v4 修改版安装教程（免费开源的网络嗅探抓包工具）

前言 Wireshark&#xff08;前称Ethereal&#xff09;是一款免费开源的网络嗅探抓包工具&#xff0c;世界上最流行的网络协议分析器&#xff01;网络封包分析软件的功能是撷取网络封包&#xff0c;并尽可能显示出最为详细的网络封包资料。Wireshark网络抓包工具使用WinPCAP作为…
阅读更多...
调教NewspaceGPT之GPT4o实战

调教NewspaceGPT之GPT4o实战

NewspaceGPT地址&#xff1a;https://newspace.ai0.cn 需求一&#xff1a;我需要一个创意logo 我的问题 我觉得我的描述对一个设计人员来说时精准的&#xff0c;但是不具体的。 需求描述&#xff1a;我需要一个logo。 表现司法公正和司法数字化&#xff0c;人工智能化 。 Ne…
阅读更多...
电路分析期末总结笔记下

电路分析期末总结笔记下

对称三相电路的线电流和相电流&#xff0c;线电压和相电压关系 相电压与线电压的关系 线电压定义&#xff1a;任意两相之间的电压称为线电压&#xff0c;常用符号V_L表示。 相电压定义&#xff1a;一相绕组两端的电压称为相电压&#xff0c;常用符号V_P表示。 关系&#xff1…
阅读更多...
微信聊天记录导出为电脑文件实操教程（附代码）

微信聊天记录导出为电脑文件实操教程（附代码）

写在前面 最近&#xff0c;微信中加的群有点多&#xff0c;信息根本看不过来。如果不看&#xff0c;怕遗漏了有价值的信息&#xff1b;如果一条条向上翻阅&#xff0c;实在是太麻烦。 有没有办法一键导出所有聊天记录&#xff1f; 一来翻阅更方便一点&#xff0c;二来还可以…
阅读更多...
深入了解Redis的TYPE命令

深入了解Redis的TYPE命令

Redis作为一个高性能的内存数据库&#xff0c;支持多种数据结构。在管理和操作Redis数据库时&#xff0c;了解键对应的数据类型是至关重要的。本文将深入探讨Redis的TYPE命令&#xff0c;它用于返回存储在指定键中的值的数据类型。 什么是TYPE命令&#xff1f; TYPE命令用于查…
阅读更多...
Zynq学习笔记--了解中断配置方式

Zynq学习笔记--了解中断配置方式

目录 1. 简介 2. 工程与代码解析 2.1 Vivado 工程 2.2 Vitis 裸机代码 2.3 关键代码解析 3. 总结 1. 简介 Zynq 中的中断可以分为以下几种类型&#xff1a; 软件中断&#xff08;Software Generated Interrupt, SGI&#xff09;&#xff1a;由软件触发&#xff0c;通常…
阅读更多...
CTF-pwn-虚拟化-【d3ctf-2021-d3dev】

CTF-pwn-虚拟化-【d3ctf-2021-d3dev】

文章目录 参考流程附件检查启动信息逆向分析漏洞查看设备配置信息exp 参考 https://x1ng.top/2021/11/26/qemu-pwn/ https://bbs.kanxue.com/thread-275216.htm#msg_header_h1_0 https://xz.aliyun.com/t/6562?time__1311n4%2BxnD0DRDBAi%3DGkDgiDlhjmYh2xuCllx7whD&alic…
阅读更多...
[Linux] Shell

[Linux] Shell

chsh不是一种sh,而是一个命令行使用程序&#xff0c;用于更改默认shell CentOS是个开源软件&#xff0c;没有sh,sh是商业版的&#xff0c; 按ls /bin/*sh显示的sh实际上是个链接文件&#xff0c;连接的bash 在命令行输入新的sh名&#xff0c;会启动一个新的进程&#xff0c; 输…
阅读更多...
计算机网络知识点汇总

计算机网络知识点汇总

计算机网络知识点汇总 第1章计算机网络体系结构 1.1 计算机网络概述 1.1.1 计算机网络的概念 ​ 计算机网络是由若干个结点(node)和连接这些结点的链路(link)组成。网络中的结点可以是就三级、集线器、交换机、或者路由器等&#xff0c;网络之间通过路由器进行互联&#xf…
阅读更多...
【Java】已解决java.sql.SQLException异常

【Java】已解决java.sql.SQLException异常

文章目录 一、分析问题背景二、可能出错的原因三、错误代码示例四、正确代码示例五、注意事项 已解决java.sql.SQLException异常 在Java中&#xff0c;java.sql.SQLException是一个通用的异常类&#xff0c;用于表示在数据库操作中发生的错误。无论是类型错误、数据类型不匹配…
阅读更多...
IF=9.3！MIMIC-IV数据库发文，手到擒来！| MIMIC-IV数据库周报（6.5~6.11）

IF=9.3！MIMIC-IV数据库发文，手到擒来！| MIMIC-IV数据库周报（6.5~6.11）

重症医学数据库&#xff08;MIMIC&#xff09;是由计算生理学实验室开发的公开数据集&#xff0c;其中包括与数千个重症监护病房入院相关的去识别化健康数据&#xff0c;致力于推动临床信息学、流行病学和机器学习的研究。 MIMIC数据库于2003年在美国国立卫生研究院的资助下&am…
阅读更多...
Springboot开发Webservice服务端和客户端

Springboot开发Webservice服务端和客户端

环境说明 Java JDK 1.8、Spring boot 2.1.6、Apache CXF 3.1.6 POM依赖 <dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId><version>2.1.6</version&…
阅读更多...
MySQL limit子句用法及优化（Limit Clause Optimization）

MySQL limit子句用法及优化（Limit Clause Optimization）

在MySQL中&#xff0c;如果只想获取select查询结果的一部分&#xff0c;可以使用limit子句来限制返回记录的数量&#xff0c;limit在获取到满足条件的数据量时即会立刻终止SQL的执行。相比于返回所有数据然后丢弃一部分&#xff0c;执行效率会更高。 文章目录 一、limit子句用…
阅读更多...
嵌入式Linux：Linux系统中文件类型

嵌入式Linux：Linux系统中文件类型

目录 1、普通文件 2、目录文件 3、字符设备文件 4、块设备文件 5、符号链接文件 6、套接字文件 7、管道文件 8、stat命令和ls命令 8.1、stat命令 8.2、ls命令 9、stat、fstat、lstat函数 9.1、stat函数 9.2、fstat函数 9.3、lstat函数 在Windows系统中&#xff0…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023