Swagger3基本使用
Swagger
课程目标
Swagger简介【了解】
Springboot整合swagger【掌握】
Swagger 常用注解【掌握】
knife4j-Swagger【会用】
一、Swagger3简介
Swagger 是一系列 RESTful API 的工具,通过 Swagger 可以获得项目的⼀种交互式文档,客户端 SDK 的自 动生成等功能。Swagger 的目标是为 REST APIs 定义一个标准的、与语⾔言无关的接口,使人和计算机在看不到源码或者看不到文档或者不能通过网络流量检测的情况下,能发现和理解各种服务的功能。当服务通过 Swagger 定义,消费者就能与远程的服务互动通过少量的实现逻辑。Swagger(丝袜哥)是世界上最流行的 API 表达工具。
OpenAPI阶段的Swagger也被称为Swagger 3.0。在Swagger 2.0后,Swagger规范正式更名为OpenAPI规范,并且根据OpenAPI规范的版本号进行了更新。因此,Swagger 3.0对应的就是OpenAPI 3.0版本,它是Swagger在OpenAPI阶段推出的一个重要版本。与前几个版本相比,Swagger 3.0更加强调对RESTful API的支持和规范化,提供了更丰富和灵活的定义方式,并且可以用于自动生成文档、客户端代码、服务器代码和测试工具等。
二、Springboot整合swagger3
使用 Spring Boot 集成 Swagger 的理念是,使用用注解来标记出需要在 API 文档中展示的信息,Swagger 会根据项目中标记的注解来生成对应的 API 文档。Swagger 被号称世界上最流行的 API 工具,它提供了 API 管理的全套解决方案,API 文档管理需要考虑的因素基本都包含,这里将讲解最常用的定制内容。
-
添加依赖
org.springdoc
springdoc-openapi-starter-webmvc-ui
2.6.0
org.springdoc
springdoc-openapi-starter-webmvc-api
2.6.0
-
创建 SwaggerConfig 配置类
/**
* swagger3配置类
*/
@Configuration
public class SwaggerConfig {@Beanpublic OpenAPI openAPI(){return new OpenAPI().info(this.getInfo());}public Info getInfo(){return new Info().title("Springboot集成Swagger3") //标题.description("Springboot集成Swagger3接口说明") //项目描述.contact(new Contact().name("蜗牛学院")) //作者.version("V1.0"); //版本号} }
-
访问swagger
启动项目后输入:http://localhost:8080/swagger-ui/index.html 可看到swagger页面
如果在访问 /swagger-ui/index.html 时出现 404 。这是因为,当你访问 .html 等静态资源时,Spring MVC 默认是在你自己项目的 resources/static 目录下去找它们,如果没有,自然就是 404 。而 swagger 相关的 .html 等静态资源是在依赖包含的 swagger-ui 项目(jar包) 下。所以,你需要通过静态资源配置来『告诉』Spring MVC 当收到 swagger 相关的静态资源访问时,去对应的这个目录下找它们。
/**
* spring mvc配置类
*/
@Configuration //项目启动时加载此类
public class WebMvcConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler(“/swagger-ui/**”)
.addResourceLocations(“classpath:/META-INF/resources/webjars/springfox-swagger-ui/”);
}
} -
配置访问路径
swagger的访问路径可以自己更改- 默认路径
springdoc:
api-docs:
path: /v3/api-docs
swagger-ui:
path: /swagger-ui.html #可以改成自己喜欢的路径,如/doc.html
- 默认路径
三、knife4j-Swagger
knife4j 是 Swagger 生成 API 文档的增强解决方案,最主要是 knife4j 提供了动态字段注释功能实现 Map 来接收参数这个的接口文档生成,忽略参数属性来实现同一个实体类对不同接口生成不同的文档
-
添加依赖
前面swagger3的依赖不需要了
com.github.xiaoymin
knife4j-openapi3-jakarta-spring-boot-starter
4.3.0
-
创建配置类
/**
* swagger3配置类
*/
@Configuration
public class SwaggerConfig {
@Bean
public OpenAPI openAPI(){
return new OpenAPI().info(this.getInfo());
}public Info getInfo(){return new Info().title("Springboot集成Swagger3") //标题.description("Springboot集成Swagger3接口说明") //项目描述.contact(new Contact().name("蜗牛学院")) //作者.version("V1.0"); //版本号} }
启动项目后通过:http://127.0.0.1:8080/doc.html 访问knife4j页面
四、Swagger3 常用注解
Swagger 通过注解表明该接口会生成文档,包括接口名、请求方法、参数、返回信息等。
1、@Tag
作用于类上,一般用来对controller类进行说明
语法: @Tag(name = "用户接口", description = "用户管理相关接口")示例 :
@RestController
@Tag(name="用户操作")
public class UserController {}
2、@Operation
作用于Controller的方法上。用于对controller方法进行说明
语法:
@Operation(summary = "操作摘要",description = "操作的详细描述",operationId = "operationId",tags = "tag1",parameters = {@Parameter(name = "param1", description = "参数1", required = true),@Parameter(name = "param2", description = "参数2", required = false)})示例 :@GetMapping("/user/list")@Operation(summary = "用户列表")public List<User> userList(){return userService.finUser();}
参数说明:
- summary:简短描述
- description :更详细的描述
- hidden:是否隐藏
- tags:标签,用于分组API
- operationId:操作的唯一标识符,建议使用唯一且具有描述性的名称
- parameters:指定相关的请求参数,使用 @Parameter 注解来定义参数的详细属性。
- requestBody:指定请求的内容,使用 @RequestBody 注解來指定请求的类型。
- responses:指定操作的返回内容,使用 @ApiResponse 注解定义返回值的详细属性。
3、@Parameters
作用于Controller的方法上。@Parameters注解中包含多个 @Parameter 注解,通过@Parameter注解对controller方法中的非对象类型形参进行说明
语法:
@Parameters({@Parameter(name = "param1",description = "description",required = true,in = ParameterIn.PATH,schema = @Schema(type = "string")),@Parameter(name = "param2",description = "description",required = true,in = ParameterIn.QUERY,schema = @Schema(type = "integer"))
})示例:@GetMapping("/user/query")@Operation(summary = "根据条件查询用户")@Parameters({@Parameter(name="username",in= ParameterIn.QUERY,description = "用户名",required = true,schema = @Schema(type ="String")),@Parameter(name="age",in= ParameterIn.QUERY,description = "年龄",required = true,schema = @Schema(type ="Integer"))})public List<User> queryUser(@RequestParam(value = "username",required = true,defaultValue = "") String username,@RequestParam(value = "age",required = true,defaultValue = "0") Integer age){return userService.finUser();}
@Parameter参数说明:
- name : 指定的参数名
- in:参数来源,可选 query、header、path 或 cookie,默认为空,表示忽略
- ParameterIn.QUERY 请求参数
- ParameterIn.PATH 路径参数
- ParameterIn.HEADER header参数
- ParameterIn.COOKIE cookie 参数
- description:参数描述
- required:是否必填,默认为 false
- schema :参数的数据类型。如 schema = @Schema(type = “string”)
4、@ApiResponses
作用于Controller的方法上。@ApiResponses包含多个@ApiResponse。通过@ApiResponse对controller方法的返回值进行说明
语法:
@ApiResponse(responseCode = "200", description = "查询成功",
content = @Content(schema = @Schema(implementation = User.class)))
@ApiResponse(responseCode = "404", description = "查询失败")示例:@GetMapping("/user/query")@Operation(summary = "根据条件查询用户")@ApiResponses({@ApiResponse(responseCode = "2000",description = "多条件查询成功",content = @Content(schema = @Schema(implementation = List.class))),@ApiResponse(responseCode = "5000",description = "多条件查询失败成功")})public ResponseResult<List<User>> queryUser(){return new ResponseResult<>(2000,"OK",null);}
@ApiResponse参数说明:
- responseCode:响应的 HTTP 状态码
- description:响应信息的描述
- content:响应的内容
5、@Schema
用于FO的类上。用于对controller中对象参数对应的FO对象的属性进行说明
- vo实体类
@Data
@Tag(name = “用户Vo”, description = “接收用户信息实体类”)
public class UserVo implements Serializable {
private static final long serialVersionUID = 1L;
@Schema(name = “id”, type = “Integer”,description = “用户id”,defaultValue =“0”)
private Integer id;
@Schema(name = “username”, type = “String”,description = “用户真实姓名”,defaultValue = “”)
private String username;
@Schema(name = “birthday”, type = “LocalDateTime”,description = “生日”,defaultValue = “”)
private LocalDateTime birthday;
@Schema(name = “sex”, type = “String”,description = “性别”,defaultValue = “男”)
private String sex;
}
参数说明:
name:名称
title:标题
description:描述
example:示例值
required:是否为必须
format:属性的格式。如 @Schema(format = “email”)
maxLength 、 minLength:指定字符串属性的最大长度和最小长度
maximum 、 minimum:指定数值属性的最大值和最小值
pattern:指定属性的正则表达式模式
type: 数据类型(integer,long,float,double,string,byte,binary,boolean,date,dateTime,password),必须是字符串。如 @Schema=(type=“integer”)
implementation :具体的实现类,可以是类本身,也可以是父类或实现的接口。 - controller
@PostMapping(“/user/add”)
@Operation(summary = “添加用户”)
public ResponseResult<List> addUser(@RequestBody UserFo userFo){
return new ResponseResult<>(2000,“OK”,null);
}
五、spring security放行swagger3
修改security配置类
/*** spring security过滤器链配配置* @param http* @return* @throws Exception*/@Beanpublic SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception{//鉴权配置http.authorizeHttpRequests(authorizeHttpRequests->authorizeHttpRequests//允许所有的OPTIONS请求.requestMatchers(HttpMethod.OPTIONS,"/**").permitAll()//放行swagger3.requestMatchers(HttpMethod.GET,"/v3/api-docs/**","/doc.html","/webjars/**").permitAll().anyRequest().authenticated());//认证配置http.formLogin().successHandler(simpleAuthenticationSuccessHandler) //认证成功后的处理器.failureHandler(simpleAuthenticationFailureHandler) //认证失败后的处理器.permitAll();//这句配置很重要,新手容易忘记。放开 login.html和dologin 的访问权//退出操作配置http.logout().logoutSuccessHandler(simpLogoutSuccessHandler);//将自定义的jwtFilter添加到Spring Security过滤器链的倒数第二个以前http.addFilterAfter(jwtFilter, UsernamePasswordAuthenticationFilter.class);//认证和鉴权异常配置http.exceptionHandling().authenticationEntryPoint(simpleAuthenticationEntryPoint) //认证异常处理器.accessDeniedHandler(simpleAccessDeniedHandler); //鉴权异常处理器//前后端项目中要禁用掉sessionhttp.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS);//关闭crsf 跨域漏洞防御http.csrf(csrf-> csrf.disable());return http.build();}
相关文章:
Swagger3基本使用
Swagger 课程目标 Swagger简介【了解】 Springboot整合swagger【掌握】 Swagger 常用注解【掌握】 knife4j-Swagger【会用】 一、Swagger3简介 Swagger 是一系列 RESTful API 的工具,通过 Swagger 可以获得项目的⼀种交互式文档,客户端 SDK 的自 动…...

如何借助Java批量操作Excel文件?
最新技术资源(建议收藏) https://www.grapecity.com.cn/resources/ 前言 | 问题背景 在操作Excel的场景中,通常会有一些针对Excel的批量操作,批量的意思一般有两种: 对批量的Excel文件进行操作。如导入多个Excel文件…...
JUC并发编程_Lock锁
JUC并发编程_Lock锁 1、Lock锁介绍2、主要方法3、与 synchronized 的区别4、Condition 使用示例 1、Lock锁介绍 Java中的 Lock 锁是 java.util.concurrent.locks 包下的一个接口,它提供了比 synchronized 关键字更灵活的锁定机制。 2、主要方法 lock():…...

Unity中的功能解释(数学位置相关和事件)
向量计算 Vector3.Slerp(起点坐标,终点坐标,t),可是从起点坐标以一个圆形轨迹到终点坐标,有那么多条轨迹,那怎么办 Vector3.Slerp 进行的是沿球面插值,因此并不是沿着严格的“圆形…...
ElementPlus---Timeline 时间线组件使用示例
介绍 使用ElementPlus时间线组件在后台首页实现通知公告列表展示,使用Vue3开发。 实现代码 Vue3代码 <el-timeline><el-timeline-itemstyle"max-width: 600px"v-for"(activity, index) in activities":key"index":times…...

推荐4款2024年大家都在用的高质量翻译器。
翻译器在我们的生活中有着很重要的作用,不管是我们在学习还是工作,生活娱乐,出国旅游等场合都会派上用场,它是我们解决沟通的障碍,提高阅读效率的好帮手。我自己使用的翻译器有很多,可以给大家列举几款特别…...

Mybatis 返回 Map 对象
一、场景介绍 假设有如下一张学生表: CREATE TABLE student (id int NOT NULL AUTO_INCREMENT COMMENT 主键,name varchar(100) NOT NULL COMMENT 姓名,gender varchar(10) NOT NULL COMMENT 性别,grade int NOT NULL COMMENT 年级,PRIMARY KEY (id) ) ENGINEInnoD…...

Vue3(三)路由基本使用、工作模式(history,hash)、query传参和param传参、props配置、编程式路由导航
文章目录 一、路由的基本使用二、路由器的工作模式三、RouterLink中to的两种写法四、嵌套路由五、路由传参1. query传参2. params传参 六、路由的propos配置七、编程式路由导航 一、路由的基本使用 安装:npm i vue-router 在src/pages文件下,创建三个路…...

TypeScript概念讲解
简单来说,TypeScript 是 JavaScript 的一个超集,支持 ECMAScript 6 标准; TypeScript 由微软开发的自由和开源的编程语言; TypeScript 设计目标是开发大型应用,它可以编译成纯 JavaScript,编译出来的 Jav…...

C++ | Leetcode C++题解之第437题路径总和III
题目: 题解: class Solution { public:unordered_map<long long, int> prefix;int dfs(TreeNode *root, long long curr, int targetSum) {if (!root) {return 0;}int ret 0;curr root->val;if (prefix.count(curr - targetSum)) {ret pref…...
回复《对话损友 2》
回复《对话损友 2》 承蒙贵人挂念,亦感激贵人给予这般交流的契机(对话损友 2 -- 回复-CSDN博客)。我自身也一直期望能留存些岁月的痕迹,然而却常困惑于不知哪些事物值得铭记,哪些又应被永远忘却。 随着时光流转&#x…...

MySQL - 运维篇
一、日志 1. 错误日志 2. 二进制日志 3. 查询日志 记录了所有的增删改查语句以及DDL语句 4. 慢查询日志 二、主从复制 1. 概述 2. 原理 3. 搭建 三、分库分表 1. 介绍 2. Mycat概述 3. Mycat入门 4. Mycat配置 5. Mycat分片 6. Mycat管理及监控 四、读写分离 1. 介绍 2. 一…...
WebGIS开发及市面上各种二三维GIS开发框架对比分析
GIS前端开发是现代WebGIS应用开发中非常重要的一环,通过前端开发框架,可以实现地图展示、交互、分析等功能。本文将介绍当前市面上常用的GIS前端开发框架,并进行对比分析。 Leaflet Leaflet是一款轻量级的开源地图库,它提供了丰…...

[论文精读]TorWard: Discovery, Blocking, and Traceback of Malicious Traffic Over Tor
期刊名称:IEEE Transactions on Information Forensics and Security 发布链接:TorWard: Discovery, Blocking, and Traceback of Malicious Traffic Over Tor | IEEE Journals & Magazine | IEEE Xplore 中文译名:TorWard:…...
pytest - 多线程提速
import timedef test1_test1():time.sleep(1)assert 1 1, "11"def test1_test2():time.sleep(1)assert 1 1, "11" 上面2个函数,执行情况: 正常执行时,花费 2.08s2个进程执行时,花费 1.18s2个线程执行时&a…...
python中logging的用法
logging.error 是 Python logging 模块中的一个方法,专门用于记录错误级别(ERROR)的日志信息。logging 模块是 Python 提供的标准日志工具,用于生成各种级别的日志消息,并支持日志的格式化和存储。 logging.error 的基…...

【YOLO目标检测车牌数据集】共10000张、已标注txt格式、有训练好的yolov5的模型
目录 说明图片示例 说明 数据集格式:YOLO格式 图片数量:10000(2000张绿牌、8000张蓝牌) 标注数量(txt文件个数):10000 标注类别数:1 标注类别名称:licence 数据集下载:车牌数据…...

gdb xterm 调试 openmpi 程序
1,编写编译一个openmpi程序 迭代计算 PI 的源程序: pi_reduce.c #include <stdio.h>#include <math.h> #include <mpi.h>double f(double); double f(double x) {return (4.0/(1.0x*x)); }int main(int argc, char* argv[]) {int d…...

【STM32】江科大STM32笔记汇总(已完结)
STM32江科大笔记汇总 STM32学习笔记课程简介(01)STM32简介(02)软件安装(03)新建工程(04)GPIO输出(05)LED闪烁& LED流水灯& 蜂鸣器(06)GPIO输入(07)按键控制LED 光敏传感器控制蜂鸣器(08)OLED调试工具(09)OLED显示屏(10)EXTI外部中断(11)对射式红外传感器计次 旋转编码器…...

Java基础扫盲(二)
想看Java基础扫盲(一)的可以观看我的上篇文章Java基础扫盲 目录 String为什么设计为不可变的 String有长度限制吗 为什么JDK9将String的char[]改为byte[] 泛型中K,T,V,E,Object,?等都代表什么含义 怎么修改一个类中使用了private修饰的String类型…...

springboot 百货中心供应链管理系统小程序
一、前言 随着我国经济迅速发展,人们对手机的需求越来越大,各种手机软件也都在被广泛应用,但是对于手机进行数据信息管理,对于手机的各种软件也是备受用户的喜爱,百货中心供应链管理系统被用户普遍使用,为方…...

Lombok 的 @Data 注解失效,未生成 getter/setter 方法引发的HTTP 406 错误
HTTP 状态码 406 (Not Acceptable) 和 500 (Internal Server Error) 是两类完全不同的错误,它们的含义、原因和解决方法都有显著区别。以下是详细对比: 1. HTTP 406 (Not Acceptable) 含义: 客户端请求的内容类型与服务器支持的内容类型不匹…...

基于ASP.NET+ SQL Server实现(Web)医院信息管理系统
医院信息管理系统 1. 课程设计内容 在 visual studio 2017 平台上,开发一个“医院信息管理系统”Web 程序。 2. 课程设计目的 综合运用 c#.net 知识,在 vs 2017 平台上,进行 ASP.NET 应用程序和简易网站的开发;初步熟悉开发一…...
前端倒计时误差!
提示:记录工作中遇到的需求及解决办法 文章目录 前言一、误差从何而来?二、五大解决方案1. 动态校准法(基础版)2. Web Worker 计时3. 服务器时间同步4. Performance API 高精度计时5. 页面可见性API优化三、生产环境最佳实践四、终极解决方案架构前言 前几天听说公司某个项…...
大语言模型如何处理长文本?常用文本分割技术详解
为什么需要文本分割? 引言:为什么需要文本分割?一、基础文本分割方法1. 按段落分割(Paragraph Splitting)2. 按句子分割(Sentence Splitting)二、高级文本分割策略3. 重叠分割(Sliding Window)4. 递归分割(Recursive Splitting)三、生产级工具推荐5. 使用LangChain的…...
【算法训练营Day07】字符串part1
文章目录 反转字符串反转字符串II替换数字 反转字符串 题目链接:344. 反转字符串 双指针法,两个指针的元素直接调转即可 class Solution {public void reverseString(char[] s) {int head 0;int end s.length - 1;while(head < end) {char temp …...

WordPress插件:AI多语言写作与智能配图、免费AI模型、SEO文章生成
厌倦手动写WordPress文章?AI自动生成,效率提升10倍! 支持多语言、自动配图、定时发布,让内容创作更轻松! AI内容生成 → 不想每天写文章?AI一键生成高质量内容!多语言支持 → 跨境电商必备&am…...
Spring Boot+Neo4j知识图谱实战:3步搭建智能关系网络!
一、引言 在数据驱动的背景下,知识图谱凭借其高效的信息组织能力,正逐步成为各行业应用的关键技术。本文聚焦 Spring Boot与Neo4j图数据库的技术结合,探讨知识图谱开发的实现细节,帮助读者掌握该技术栈在实际项目中的落地方法。 …...
Java多线程实现之Thread类深度解析
Java多线程实现之Thread类深度解析 一、多线程基础概念1.1 什么是线程1.2 多线程的优势1.3 Java多线程模型 二、Thread类的基本结构与构造函数2.1 Thread类的继承关系2.2 构造函数 三、创建和启动线程3.1 继承Thread类创建线程3.2 实现Runnable接口创建线程 四、Thread类的核心…...
JS设计模式(4):观察者模式
JS设计模式(4):观察者模式 一、引入 在开发中,我们经常会遇到这样的场景:一个对象的状态变化需要自动通知其他对象,比如: 电商平台中,商品库存变化时需要通知所有订阅该商品的用户;新闻网站中࿰…...