Swagger API 文档 | SpringBoot 3.x 集成 SpringDoc

2024-04-15 07:36

本文主要是介绍Swagger API 文档 | SpringBoot 3.x 集成 SpringDoc,希望对大家解决编程问题提供一定的参考价值,需要的开发者们随着小编来一起学习吧!

文章目录

  • 常规方式
    • 第 1 步:添加依赖
    • 第 2 步:配置 API 信息及全局参数
      • 配置 OpenAPI 文档
        • 配置单个 OpenAPI 文档 - 方式 1
        • 配置单个 OpenAPI 文档 - 方式 2
        • 配置多个 OpenAPI 文档
      • 其它 SpringDoc 及 Swagger-UI 配置
    • 第 3 步:添加 Swagger3 注解
      • Swagger2 和 Swagger3 注解对应关系
      • Swagger3 注解案例
        • Feign 客户端及其实现 Controller
        • 通用 Response 与 Account 实体类
        • 界面效果
  • 特殊方式 1:从 JavaDoc 生成 API 定义
    • 第 1 步:添加依赖
    • 第 2 步:编译项目
    • 第 3 步:添加 JavaDoc 注释
    • 第 4 步:最终效果
  • 特殊方式 2:构建时生成 JSON/YAML
  • 相关博文

😎 本节目标: SpringBoot 3.x 集成 SpringDoc(含 SpringFox 升级 SpringDoc)

  • 常规方式:添加注解方式,然后生成 API 文档及 Swagger UI 界面
  • 特殊方式 1:从 JavaDoc 读取 API 定义
  • 特殊方式 2:maven 集成测试阶段生成 API 定义

👉 版本说明

  • JDK 17
  • SpringBoot 3.2.1
  • SpringDoc 2.3.0

🚀 官方 demo:springdoc-openapi-demos-2.x.zip

常规方式

第 1 步:添加依赖

移除 SpringFox 和 Swagger2 的相关依赖,并添加 springdoc-openapi-starter-webmvc-ui 依赖:

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.3.0</version>
</dependency>

添加上述依赖后,即可访问 SwaggerUI 界面及 OpenAPI 文档。
Swagger-UI 访问效果:http://server:port/context-path/swagger-ui.html
image.png
OpenAPI 访问效果:

  • JSON 格式: http://server:port/context-path/v3/api-docs
  • YAML 格式:http://server:port/context-path/v3/api-docs.yaml

image.png

第 2 步:配置 API 信息及全局参数

上述 Swagger UI 界面中,使用的是默认的 API 信息。下面我们来自定义:

  • 添加 API 信息,比如标题、描述等
  • 添加全局请求 Token

下面有几种方式,可按需选择。

配置 OpenAPI 文档

配置单个 OpenAPI 文档 - 方式 1

在配置前,我们先了解一个特性:Swagger 中的有些注解,支持 Spring 配置解析。

  • @Info: title * description * version * termsOfService
  • @Info.license: name * url
  • @Info.contact: name * email * url
  • @Operation: description * summary
  • @Parameter: description * name
  • @ApiResponse: description
  • @OAuthFlow: openIdConnectUrl * authorizationUrl * refreshUrl * tokenUrl
  • @Schema: name * title * description,但需要设置 springdoc.api-docs.resolve-schema-properties=true

利用这个特性,我们使用如下配置文件进行自定义 API 信息及全局配置:

@OpenAPIDefinition(info = @Info(title = "${openapi.title: ${spring.application.name}} API文档",version = "${openapi.version: 0.0.1}",description = "${openapi.description:}",termsOfService = "${openapi.termsOfService:}",license = @License(name = "${openapi.license.name:}",url = "${openapi.license.url:}"),contact = @Contact(name = "${openapi.contact.name:}",email = "${openapi.contact.email:}",url = "${openapi.contact.url:}")),security = @SecurityRequirement(name = "JWT")
)
@SecurityScheme(type = SecuritySchemeType.HTTP, name = "JWT", scheme = "Bearer", in = SecuritySchemeIn.HEADER)
@Configuration
public class SpringDocConfig {}

这样,我们可以使用 openapi.title 定义 API 标题,使用 openapi.version 定义 API 版本。比如:

openapi:title: 业务服务version: v1.0.0

页面效果:
image.png此外,前面定义了安全配置,即每个请求需要在请求头中加 Bearer token。在上述页面中,显示了 Authorize 按钮,可以输入 Token 值。
image.png
后续请求,就会自动带着这个 Bearer Token:
image.png

配置单个 OpenAPI 文档 - 方式 2

换个方式,一样可以实现。可以直接构造 OpenAPI 这个对象,而不是使用注解来定义。
思路和之前一样:

  • 先定义安全 Schema:@SecurityScheme -> addSecuritySchemes
  • 然后使用组件:security = xxx -> .addSecurityItem
@Configuration
public class SpringDocConfig {@Beanpublic OpenAPI customOpenAPI(@Value("${springdoc.version:1.0.0}") String appVersion) {return new OpenAPI()// 定义组件.components(new Components().addSecuritySchemes("JWT", new SecurityScheme().in(SecurityScheme.In.HEADER).type(SecurityScheme.Type.HTTP)

这篇关于Swagger API 文档 | SpringBoot 3.x 集成 SpringDoc的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/905219

相关文章

springboot健康检查监控全过程

《springboot健康检查监控全过程》文章介绍了SpringBoot如何使用Actuator和Micrometer进行健康检查和监控,通过配置和自定义健康指示器,开发者可以实时监控应用组件的状态,... 目录1. 引言重要性2. 配置Spring Boot ActuatorSpring Boot Act

使用Java解析JSON数据并提取特定字段的实现步骤(以提取mailNo为例)

《使用Java解析JSON数据并提取特定字段的实现步骤(以提取mailNo为例)》在现代软件开发中,处理JSON数据是一项非常常见的任务,无论是从API接口获取数据,还是将数据存储为JSON格式,解析... 目录1. 背景介绍1.1 jsON简介1.2 实际案例2. 准备工作2.1 环境搭建2.1.1 添加

Java实现任务管理器性能网络监控数据的方法详解

《Java实现任务管理器性能网络监控数据的方法详解》在现代操作系统中,任务管理器是一个非常重要的工具,用于监控和管理计算机的运行状态,包括CPU使用率、内存占用等,对于开发者和系统管理员来说,了解这些... 目录引言一、背景知识二、准备工作1. Maven依赖2. Gradle依赖三、代码实现四、代码详解五

java如何分布式锁实现和选型

《java如何分布式锁实现和选型》文章介绍了分布式锁的重要性以及在分布式系统中常见的问题和需求,它详细阐述了如何使用分布式锁来确保数据的一致性和系统的高可用性,文章还提供了基于数据库、Redis和Zo... 目录引言:分布式锁的重要性与分布式系统中的常见问题和需求分布式锁的重要性分布式系统中常见的问题和需求

SpringBoot基于MyBatis-Plus实现Lambda Query查询的示例代码

《SpringBoot基于MyBatis-Plus实现LambdaQuery查询的示例代码》MyBatis-Plus是MyBatis的增强工具,简化了数据库操作,并提高了开发效率,它提供了多种查询方... 目录引言基础环境配置依赖配置(Maven)application.yml 配置表结构设计demo_st

在Ubuntu上部署SpringBoot应用的操作步骤

《在Ubuntu上部署SpringBoot应用的操作步骤》随着云计算和容器化技术的普及,Linux服务器已成为部署Web应用程序的主流平台之一,Java作为一种跨平台的编程语言,具有广泛的应用场景,本... 目录一、部署准备二、安装 Java 环境1. 安装 JDK2. 验证 Java 安装三、安装 mys

Springboot的ThreadPoolTaskScheduler线程池轻松搞定15分钟不操作自动取消订单

《Springboot的ThreadPoolTaskScheduler线程池轻松搞定15分钟不操作自动取消订单》:本文主要介绍Springboot的ThreadPoolTaskScheduler线... 目录ThreadPoolTaskScheduler线程池实现15分钟不操作自动取消订单概要1,创建订单后

JAVA中整型数组、字符串数组、整型数和字符串 的创建与转换的方法

《JAVA中整型数组、字符串数组、整型数和字符串的创建与转换的方法》本文介绍了Java中字符串、字符数组和整型数组的创建方法,以及它们之间的转换方法,还详细讲解了字符串中的一些常用方法,如index... 目录一、字符串、字符数组和整型数组的创建1、字符串的创建方法1.1 通过引用字符数组来创建字符串1.2

SpringCloud集成AlloyDB的示例代码

《SpringCloud集成AlloyDB的示例代码》AlloyDB是GoogleCloud提供的一种高度可扩展、强性能的关系型数据库服务,它兼容PostgreSQL,并提供了更快的查询性能... 目录1.AlloyDBjavascript是什么?AlloyDB 的工作原理2.搭建测试环境3.代码工程1.

Java调用Python代码的几种方法小结

《Java调用Python代码的几种方法小结》Python语言有丰富的系统管理、数据处理、统计类软件包,因此从java应用中调用Python代码的需求很常见、实用,本文介绍几种方法从java调用Pyt... 目录引言Java core使用ProcessBuilder使用Java脚本引擎总结引言python