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

在这里插入图片描述

😄 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中生成接口文档了。如果本文对您有所帮助，希望 一键三连 给博主一点点鼓励，如果您有任何疑问或建议，请随时留言讨论！

在这里插入图片描述

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

如若内容造成侵权/违法违规/事实不符，请联系我们进行投诉反馈qq邮箱809451989@qq.com，一经查实，立即删除！

相关文章

MySQL锁和使用

MySQL锁和使用

在MySQL中&#xff0c;锁用于控制并发访问&#xff0c;以保证数据的一致性和完整性。MySQL提供了多种类型的锁&#xff0c;包括表级锁、行级锁和页面级锁。以下是MySQL中各种锁的详细介绍及其使用方法&#xff1a; 1. 表级锁&#xff08;Table Locks&#xff09; 表级锁用于锁…
阅读更多...
Studying-代码随想录训练营day22| 回溯理论基础、77.组合、216.组合总和II、17.电话号码的字母组合

Studying-代码随想录训练营day22| 回溯理论基础、77.组合、216.组合总和II、17.电话号码的字母组合

第22天&#xff0c;回溯章节开始&#xff01;一大算法难点&#xff0c;加油加油&#xff01; 回溯理论基础组合问题的剪枝操作 文档讲解&#xff1a;代码随想录回溯理论基础 视频讲解&#xff1a;回溯理论基础 回溯法也叫回溯搜索法&#xff0c;它是一种搜索&#xff0c;遍历的…
阅读更多...
Python 算法交易实验73 QTV200第二步: 数据清洗并写入ClickHouse

Python 算法交易实验73 QTV200第二步: 数据清洗并写入ClickHouse

说明 先检查一下昨天启动的worker是否正常工作&#xff0c;然后做一些简单的清洗&#xff0c;存入clickhouse。 内容 1 检查数据 from Basefuncs import * # 将一般字符串转为UCS 名称 def dt_str2ucs_blockname(some_dt_str):some_dt_str1 some_dt_str.replace(-,.).re…
阅读更多...
【日记】软考居然一次过了（620 字）

【日记】软考居然一次过了（620 字）

正文 早上空闲的时候&#xff0c;上 QQ 看了一下&#xff0c;许久不见动静的系统架构设计师群有人说出分了。我想高级都出分了&#xff0c;中级应该也出来了&#xff0c;于是用手机查了一下。看到分数几乎快要泪从中来。为什么软考能一次过&#xff0c;银行从业资格证考了两三…
阅读更多...
学生表的er关系图和模型图

学生表的er关系图和模型图

er关系图 模型图
阅读更多...
放烟花短视频素材去哪里找？去哪里下载？烟花素材网分享

放烟花短视频素材去哪里找？去哪里下载？烟花素材网分享

在当代社会&#xff0c;短视频凭借其独有的魅力成为大众传递情感、记录生活、分享快乐的新兴方式。特别是在庆祝节日和特殊时刻时&#xff0c;烟花的绚丽效果常常被用来吸引观众的目光&#xff0c;成为视频作品中的亮点。然而&#xff0c;对于短视频制作者来说&#xff0c;寻找…
阅读更多...
【SCAU操作系统】期末复习简答及计算题例题解析

【SCAU操作系统】期末复习简答及计算题例题解析

一、写出下列英文缩写词在计算机系统中的英文或中文全名。 OS: Operating System 操作系统PSW: Program Status Word 程序状态字FCFS: First Come First Serve 先来先服务PCB: Process Control Block 进程控制块DMA: Direct Memory Access 直接存储器存取MMU: Memory Manageme…
阅读更多...
Does a vector database maintain pre-vector chunked data for RAG systems?

Does a vector database maintain pre-vector chunked data for RAG systems?

题意&#xff1a;一个向量数据库是否为RAG系统维护预向量化分块数据&#xff1f; 问题背景&#xff1a; I believe that when using an LLM with a Retrieval-Augmented Generation (RAG) approach, the results retrieved from a vector search must ultimately be presented…
阅读更多...
从源码到上线：直播带货系统与短视频商城APP开发全流程

从源码到上线：直播带货系统与短视频商城APP开发全流程

很多人问小编&#xff0c;一个完整的直播带货系统和短视频商城APP是如何从源码开发到最终上线的呢&#xff1f;今天&#xff0c;笔者将详细介绍这一全过程。 一、需求分析与规划 1.市场调研与需求分析&#xff1a;首先需要进行市场调研&#xff0c;了解当前市场的需求和竞争情…
阅读更多...
Flutter学习：从搭建环境到运行

Flutter学习：从搭建环境到运行

一、开发环境的搭建 本文所示内容都是在Windows系统下进行的。 1、下载 Flutter SDK Flutter 官网&#xff08;https://docs.flutter.cn/release/archive?tabwindows&#xff09; 或者通过 git clone -b master https://github.com/flutter/flutter.git 下载 2、配置环境…
阅读更多...
VMware 最新的安全漏洞公告VMSA-2024-0013

VMware 最新的安全漏洞公告VMSA-2024-0013

#深度好文计划# 一、摘要 2024年6月26日&#xff0c;VMware 发布了最新的安全漏洞公告 VMSA-2024-0013&#xff0c;修复了 VMware ESXi 和 VMware vCenter 中的多个安全漏洞。 VMSA-2024-0013&#xff1a;VMware ESXi 和 vCenter Server 更新修正了多个安全性漏洞 &#xff…
阅读更多...
datax入门（datax的安装与简单使用）——01

datax入门（datax的安装与简单使用）——01

datax入门&#xff08;datax的安装与简单使用&#xff09;——01 1. 官网2. 工具部署&#xff08;通过下载DataX工具包&#xff09;2.1 下载、解压2.2 配置2.2.1 查看配置模版2.2.2 根据模版配置json2.2.3 启动DataX 3. datax的简单使用3.1 mysql2stream3.2 mysql2mysql3.2.1 拼…
阅读更多...
评估大型语言模型生成文章的能力

评估大型语言模型生成文章的能力

1. AI解读 1.1. 总体概要 本文探讨了大型语言模型&#xff08;LLMs&#xff09;如GPT-4在生成特定领域&#xff08;如计算机科学中的自然语言处理NLP&#xff09;教育调查文章方面的能力和局限性。研究发现&#xff0c;尽管GPT-4能够根据特定指导生成高质量的调查文章&#x…
阅读更多...
使用jupyter打开本地ipynb文件的方法

使用jupyter打开本地ipynb文件的方法

常用方法&#xff1a; 先启动jupyter&#xff0c;然后在打开的页面点击upload&#xff0c;选择想要打开的文件上传然后打开&#xff0c;但是这样其实是先复制了一份到jupyter中&#xff0c;然后打开运行。而我不想复制。 方法二 先打开项目文件所在文件夹&#xff0c;文件夹…
阅读更多...
背靠广汽、小马智行，如祺出行打得过滴滴和百度吗？

背靠广汽、小马智行，如祺出行打得过滴滴和百度吗？

©自象限原创 作者丨艾AA 编辑丨薛黎 北京时间6月14日凌晨&#xff0c;在特斯拉股东大会上&#xff0c;马斯克阐述了对Robotaxi&#xff08;自动驾驶出租车&#xff09;商业模式的构想——特斯拉不仅会运营自己的无人驾驶出租车车队&#xff0c;还可以让特斯拉车主们的爱…
阅读更多...
Flutter学习目录

Flutter学习目录

学习Dart语言 官网&#xff1a;https://dart.cn/ 快速入门&#xff1a;Dart 语言开发文档&#xff08;dart.cn/guides&#xff09; 学习Flutter Flutter生命周期 点击跳转Flutter更换主题 点击跳转StatelessWidget和StatefulWidget的区别 点击跳转学习Flutter中新的Navigato…
阅读更多...
一文入门CMake

一文入门CMake

我们前几篇文章已经入门了gcc和Makefile&#xff0c;现在可以来玩玩CMake了。 CMake和Makefile是差不多的&#xff0c;基本上是可以相互替换使用的。CMAke可以生成Makefile&#xff0c;所以本质上我们还是用的Makefile&#xff0c;只不过用了CMake就不用再写Makefile了&#x…
阅读更多...
Spring底层原理之bean的加载方式四 @import 注解

Spring底层原理之bean的加载方式四 @import 注解

bean的加载方式四 import 第四种bean的导入方式 是import导入的方式 在配置类上面加上注解就行 package com.bigdata1421.config;import com.bigdata1421.bean.Dog; import org.springframework.context.annotation.Import;Import(Dog.class) public class SpringConfig4 {…
阅读更多...
Linux高级编程——进程

Linux高级编程——进程

1.进程的含义? 进程是一个程序执行的过程&#xff0c;会去分配内存资源&#xff0c;cpu的调度 PID, 进程标识符 当前工作路径 chdir umask 0002 进程打开的文件列表 文件IO中有提到 &#xff08;类似于标准输入 标准输出的编号&#xff0c;系统给0&#xff0c;1&#xf…
阅读更多...
点云处理实战 点云平面拟合

点云处理实战 点云平面拟合

目录 一、什么是平拟合 二、拟合步骤 三、数学原理 1、平面拟合 2、PCA过程 四、代码 一、什么是平拟合 平面拟合是指在三维空间中找到一个平面，使其尽可能接近给定的点云。最小二乘法是一种常用的拟合方法，通过最小化误差平方和来找到最优的拟合平面。 二、拟合步骤…
阅读更多...
最新文章

Copyright @ 2022~2023