【SpringBoot整合系列】SpringBoot3.x整合Swagger

目录

  • 产生背景
  • 官方解释:
  • 作用
  • SpringBoot3整合Swagger注意事项
  • swagger3 常用注解
  • SpringBoot3.x整合Swagger
    • 1.创建工程(jdk:17,boot:3.2.4)
    • 2.引入pom依赖
    • 3.application.yml添加配置
    • 4.添加swagger3.0配置
    • 5.控制器层(Controller)
    • 6.模型层(Model)
    • 7.启动并测试
      • 【Get请求接口】/swagger/student接口详情
      • Model详情
      • 【POST请求接口】/swagger/student

产生背景

  • 随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了前后端分离的形态,而且前 端技术和后端技术在各自的道路上越走越远。前端和后端的唯一联系,变成了 API 接口,所以 API 文档 变成了前后端开发人员联系的纽带,变得越来越重要。

  • 那么问题来了,随着代码的不断更新,开发人员在开发新的接口或者更新旧的接口后,由于开发任务的 繁重,往往文档很难持续跟着更新,Swagger 就是用来解决该问题的一款重要的工具,对使用接口的人 来说,开发人员不需要给他们提供文档,只要告诉他们一个 Swagger 地址,即可展示在线的 API 接口 文档,除此之外,调用接口的人员还可以在线测试接口数据,同样地,开发人员在开发接口时,同样也 可以利用 Swagger 在线接口文档测试接口数据,这给开发人员提供了便利。

官方解释:

Swagger是全球最大的OpenAPI规范(OAS)API开发工具框架,支持从设计和文档到测试和部署的整个API生命周期的开发。Swagger是⼀个⽤于⽣成服务器接⼝的规范性⽂档、并且能够对接⼝进⾏测试的⼯具。

简单来说:Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化Restful风格的web服务。

作用

  • 接口的文档在线自动生成
  • 功能测试

SpringBoot3整合Swagger注意事项

SpringBoot3+jdk17的情况下,swagger的V2和V3都是不行的。这里使用spring官方出品的springdoc-openapi。在使用springdoc-openapi的时候也有很多坑,首先springdoc-openapi的v1.x.x版本也是不行的,springdoc-openapi的版本必须是v2.x.x以上。

swagger3 常用注解

注解SpringBoot3 版本替换旧注解 SpringBoot2 版本描述
@Tag@Api用于标注一个Controller(Class)。在默认情况下,Swagger-Core只会扫描解析具有@Api注解的类,而会自动忽略其他类别资源(JAX-RS endpoints,Servlets等等)的注解。
@Operation@ApiOperation用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。
@Parameter@ApiParam@Parameter作用于请求方法上,定义api参数的注解。
@Parameters、@Parameter@ApiImplicitParams、@ApiImplicitParam都可以定义参数
(1)@Parameters:用在请求的方法上,包含一组参数说明
(2)@Parameter:对单个参数的说明
io.swagger.v3.oas.annotations新包中的@ApiResponses、@ApiResponse旧包io.swagger.annotations中的@ApiResponses、@ApiResponse进行方法返回对象的说明。
@Schema@ApiModel、@ApiModelProperty@Schema用于描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景)。

SpringBoot3.x整合Swagger

1.创建工程(jdk:17,boot:3.2.4)

项目结构:
在这里插入图片描述

2.引入pom依赖

       <!-- openAPI包,替换 Swagger 的 SpringFox --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.2.0</version></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>

3.application.yml添加配置

spring:mvc:pathmatch:matching-strategy: ant_path_matcher

4.添加swagger3.0配置

package com.example.config;import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;/*** @author: Susheng* @datetime: 2024/3/26* @desc:*/
@Configuration
public class OpenAPIConfig {@Beanpublic OpenAPI openAPI() {return new OpenAPI().info(new Info().title("接口文档标题").description("SpringBoot3 集成 Swagger3接口文档").version("v1")).externalDocs(new ExternalDocumentation().description("项目API文档").url("/"));}
}

5.控制器层(Controller)

package com.example.controller;import com.example.model.SwaggerApiModel;
import io.swagger.v3.oas.annotations.Hidden;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
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 org.springframework.web.bind.annotation.*;
/*** @author: zjl* @datetime: 2024/3/26* @desc:*/
@Tag(name = "控制器:测试Swagger3", description = "描述:测试Swagger3")
@RestController
public class SwaggerController {@Operation(summary = "测试Swagger3注解方法Get")@Parameters({@Parameter(name = "id",description = "编码"),@Parameter(name = "headerValue",description = "header传送内容")})@ApiResponses({@ApiResponse(responseCode = "200", description = "请求成功"),@ApiResponse(responseCode = "400", description = "请求参数没填好"),@ApiResponse(responseCode = "401", description = "没有权限"),@ApiResponse(responseCode = "403", description = "禁止访问"),@ApiResponse(responseCode = "404", description = "请求路径没有或页面跳转路径不对")})@GetMapping(value = "/swagger/student")public Object getStudent(@RequestParam @Parameter(example = "2")  String id,@RequestHeader @Parameter(example = "2") String headerValue){return id;}@Operation(summary = "测试Swagger3注解方法Post")@ApiResponses({@ApiResponse(responseCode = "200", description = "请求成功"),@ApiResponse(responseCode = "400", description = "请求参数没填好"),@ApiResponse(responseCode = "401", description = "没有权限"),@ApiResponse(responseCode = "403", description = "禁止访问"),@ApiResponse(responseCode = "404", description = "请求路径没有或页面跳转路径不对")})@PostMapping(value = "/swagger/student", produces = "application/json")public SwaggerApiModel updateStudent(@RequestBody SwaggerApiModel model){return model;}/*** swagger 不暴漏该 api,通过@Hidden隐藏* 但是仍然可以访问* @return*/@Hidden@GetMapping(value = "/swagger/hiddenApi")public String hiddenApi(){return "hiddenApi";}/*** swagger 暴漏该 api,没有配置@Hidden会展示* @return*/@GetMapping(value = "/swagger/noHiddenApi")public String noHiddenApi(){return "noHiddenApi";}
}

6.模型层(Model)

package com.example.model;import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;import java.io.Serializable;/*** @author: zjl* @datetime: 2024/3/26* @desc:*/
@Data
@Schema(description= "学生信息")
public class SwaggerApiModel implements Serializable {@Schema(description = "主键ID", required = true, example = "1")private Long id;@Schema(description = "手机号", required = true)private String phonenum;@Schema(description = "密码", required = true)private String password;@Schema(description = "年龄", required = true)private Integer age;}

7.启动并测试

启动服务后,首先通过浏览器打开链接http://localhost:9090/swagger-ui/index.html
在这里插入图片描述

【Get请求接口】/swagger/student接口详情

  • 入参
    在这里插入图片描述

  • 响应模板在这里插入图片描述

  • 接口测试
    在这里插入图片描述

  • 接口测试结果
    在这里插入图片描述

Model详情

在这里插入图片描述

【POST请求接口】/swagger/student

在这里插入图片描述在这里插入图片描述

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

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

相关文章

一、Spring Cloud(Base工程构建)

一、Spring Cloud&#xff08;Base工程构建&#xff09; 1.1 Spring Cloud 简述 1.1.1 Spring Cloud 版本推荐 在讲解 Spring Cloud 之前&#xff0c;首先推荐一下各个依赖的版本&#xff0c;以免出现版本错误 版本推荐 必须根据以上版本&#xff0c;否则可能会出现一些不…

鸿蒙harmonyOS常用基础标签、组件、事件等用法介绍

基础组件 text &#xff1a; 字体标签&#xff0c;汉字显示必须用字体组件包裹&#xff0c;规范规定&#xff0c;不写不显示image&#xff1a;图片标签&#xff0c;属性&#xff1a;src&#xff0c;路径相对路径…/方式button&#xff1a;按钮标签&#xff0c;属性&#xff1a…

Hana数据库 No columns were bound prior to calling SQLFetch or SQLFetchScroll

在php调用hana数据库的一个sql时报错了&#xff0c;查表结构的sql&#xff1a; select * from sys.table_columns where table_name VBAP SQLSTATE[SL009]: <<Unknown error>>: 0 [unixODBC][Driver Manager]No columns were bound prior to calling SQLFetch …

智能小程序开发 —— meature API 汇总(二)

resetStatistics 重置设备的统计数据。 注意&#xff1a;该方法会清空统计数据&#xff0c;请注意使用方式&#xff01; 请求参数 参数数据类型说明是否必填devIdstring设备 ID是 请求示例 // ray-js/ray^1.2.12 import {resetStatistics} from ray-js/ray;resetStatisti…

基于SpringBoot和Leaflet的行政区划地图掩膜效果实战

目录 前言 一、掩膜小知识 1、GIS掩膜的实现原理 2、图层掩膜流程 二、使用插件 1、leaflet-mask介绍 2、核心代码解释 三、完整实例实现 1、后台逻辑实现 2、省级行政区划查询实现 3、行政区划定位及掩膜实现 4、成果展示 总结 前言 在之前的博客提过按空间矢量…

hadoop 常用命令

hadoop 常用命令 hadoop fs -mkdir /test hadoop fs -put /opt/frank/tb_test03.txt /test/ hadoop fs -ls /test/ hadoop fs -cat /test/tb_test03.txt hadoop fs -rm /test/tb_test03.txt hadoop dfs 也能使用、但不推荐&#xff0c;执行会提示&#xff1a; DEPRECATED: Us…

GPT大语言模型助力R语言开展数据统计分析

自2022年GPT&#xff08;Generative Pre-trained Transformer&#xff09;大语言模型的发布以来&#xff0c;它以其卓越的自然语言处理能力和广泛的应用潜力&#xff0c;在学术界和工业界掀起了一场革命。在短短一年多的时间里&#xff0c;GPT已经在多个领域展现出其独特的价值…

【STM32+HAL】I2C+DMA读取AS5600编码器

一、DMA的应用 有关更多DMA的应用&#xff0c;详见【STM32HAL】DMA应用 二、HAL库配置 1、开启I2C 开启对应DMA及中断 2、开启串口通信 至此&#xff0c;HAL库配置完毕 三、DMA版&#xff08;高效但不稳定&#xff09; 1、as5600.c #include "AS5600.h" #includ…

数据结构与算法 顺序表的基本运算

一、实验内容 编写一个程序实现&#xff0c;实现顺序表的各种基本运算&#xff08;假设顺序表的元素类型为char&#xff09;&#xff0c;并以此为基础设计一个程序完成下列功能&#xff1a; &#xff08;1&#xff09;初始化顺序表&#xff1b; &#xff08;2&#xff09;采…

docker 安装 kibana

使用Docker安装Kibana相对简单且易于管理。以下是使用Docker安装Kibana的基本步骤&#xff1a; 安装Docker&#xff1a; 确保你的CentOS系统上已经安装了Docker。如果没有&#xff0c;请按照以下命令安装&#xff1a; sudo yum install -y yum-utils device-mapper-persistent-…

用指针处理链表(二)

4建立动态链表 所谓建立动态链表是指在程序执行过程中从无到有地建立起一个链表&#xff0c;即一个一个地开辟结点和输入各结点数据,并建立起前后相链的关系。 例11.8 写一函数建立一个有3名学生数据的单向动态链表。 先考虑实现此要求的算法(见图11.12)。 设3个指针变量:he…

企业级快速开发框架 nbsaas-boot 1.1.8-2024 发布了

<parent><groupId>com.nbsaas.boot</groupId><artifactId>nbsaas-boot</artifactId><version>1.1.8-2024</version> </parent> 本次更新内容 1. 重构代码生成器&#xff0c;采用类提取和字段提取两种方式&#xff0c;提取功能…

HDFSRPC通信框架详解

本文主要对HDFSRPC通信框架解析。包括listener&#xff0c;reader&#xff0c;handler&#xff0c;responser等实现类的源码分析。注意hadoop版本为3.1.1。 写在前面 rpc肯定依赖于socket通信&#xff0c;并且使用的是java NIO。读者最好对nio有一定的了解&#xff0c;文章中…

HTML5 、CSS3 、ES6 新特性

HTML5 新特性 1. 新的语义化元素&#xff1a;article 、footer 、header 、nav 、section 2. 表单增强&#xff0c;新的表单控件&#xff1a;calendar 、date 、time 、email 、url 、search 3. 新的 API&#xff1a;音频(用于媒介回放的 video 和 audio 元素)、图形&#x…

古河云科技校园数字孪生解决方案

智慧校园需将环境信息、资源信息和应用信息全部转化为数字化信息&#xff0c;为管理决策和服务提供强有力的支持。智慧系统集智能化感知、智能化控制、智能化管理、智能化互动反馈、智能化数据分析、智能化视窗等功能于一体&#xff0c;旨在实现校园信息服务的全面提升。 行业…

教程1_图像视频入门

一、图像入门 1、cv2.imread()函数 cv2.imread() 是 OpenCV 库中的一个函数&#xff0c;用于读取图像文件。下面是 cv2.imread() 函数的基本介绍和使用方法&#xff1a; 函数定义 cv2.imread(filename, flagscv2.IMREAD_COLOR) 参数 filename&#xff1a;要读取的图像的路…

使用Spring Data Elasticsearch实现与Elasticsearch的集成,进行全文搜索和数据分析。

使用Spring Data Elasticsearch实现与Elasticsearch的集成&#xff0c;进行全文搜索和数据分析。 使用Spring Data Elasticsearch可以很容易地实现与Elasticsearch的集成&#xff0c;从而进行全文搜索和数据分析。下面是一个简单的示例&#xff0c;演示如何在Spring Boot应用程…

Excel 导入、导出的封装

最近在封装公司统一使用的组件&#xff0c;主要目的是要求封装后开发人员调用简单&#xff0c;不用每个项目组中重复去集成同一个依赖l&#xff0c;写的五花八门&#xff0c;代码不规范&#xff0c;后者两行泪。 为此&#xff0c;我们对EasyExcel进行了二次封装&#xff0c;我…

flutter const InviteFriendReward(),用setState刷新不了

列布局里面添加了InviteFriendReward()&#xff0c;InviteFriendReward()里面有请求接口的开关是否显示&#xff0c;但是因为里面有波浪形&#xff0c;所以加了const&#xff0c;导致setState时&#xff0c;即使开关是开的&#xff0c;也没有再显示了 const InviteFriendRewar…

python怎样打开一个pdf文件?

要在Python中打开PDF文件&#xff0c;可以使用PyPDF2库。 首先&#xff0c;确保已安装PyPDF2库&#xff0c;可以使用以下命令安装&#xff1a; pip install PyPDF2 然后&#xff0c;可以按照以下步骤打开PDF文件&#xff1a; 导入PyPDF2库&#xff1a; import PyPDF2 打开…