Swagger使用教程及Swagger增强工具knife4j

article/2025/10/10 18:27:39

标题

  • 课外知识须知
    • 什么是swagger
    • 什么是RESTful 面向资源
    • URI和URL区别：
  • 博址推荐
  • SpringBoot集成Swagger
  • Swagger常用注解
  • Swagger增强工具knife4j

重点掌握：编写swagger的配置文件，理解每个配置的作用

课外知识须知

Swagger官网：

什么是swagger

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger让部署管理和使用功能强大的API变得非常简单。
简单来说，就是后端给前端提供的一个可以查看各种接口的方法、类型等。

作用：

  1. 接口的文档在线自动生成。
  2. 功能测试。
    在这里插入图片描述
    在这里插入图片描述
    在这里插入图片描述

在这里插入图片描述

什么是RESTful 面向资源

简单的说：RESTful是一种架构的规范与约束、原则，符合这种规范的架构就是RESTful架构。

REST是英文representational state transfer(表现层状态转变)或者表述性状态转移，准确的说是Resource Representational State Transfer（资源表述性状态转移），就是资源在网络中以某种表现形式进行状态转化。Rest是web服务的一种架构风格；使用HTTP，URI，XML，JSON，HTML等广泛流行的标准和协议；轻量级，跨平台，跨语言的架构设计，它是一种设计风格，不是一种标准，是一种思想。

资源
“资源”是RESTful中最核心的概念之一。在RESTful概念中，互联网中的每一样信息都可以定义为资源，比如文本、图片、音频、视频等。而这些资源又都可以对应一个特定的URI(统一资源定位符)，URI为每一个资源的地址或独一无二的识别符。

表现层
针对上面的“资源”，我们要进行相应的呈现，而且可以采用多种的呈现形式，而这些呈现形式就叫做“表现层”。
就拿文本为例，我们可以呈现为JSON格式、XML格式、HTML格式，甚至二进制格式等。这就是表现层所做的事情。

状态转化
资源通常放在服务器端，而客户端对服务器资源的增、删、改、查等操作，便涉及到资源状态的转化。这个过程便是“ 状态转化”。

我们以HTTP协议为例（RESTful不仅仅适用HTTP协议，只不过经常以HTTP协议为衬托），客户端可通过一些操作让服务器端的资源发生变化。而这整个过程，便是“表现层状态转化”。

在HTTP中，提供了四种常见的操作方式：GET、POST、PUT、DELETE。这四种操作方式分别对应四种基本操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源。

在这里插入图片描述

在这里插入图片描述

在这里插入图片描述

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

URI和URL区别：

URI和URL的区别
URI和URL的区别比较与理解

在这里插入图片描述

URI只是一种概念，怎样实现无所谓，只要它唯一标识一个资源就可以了。
URL是URI的一个子集，是Internet上描述信息资源的字符串，主要用在各种WWW客户程序和服务器程序上，是URI概念的一种实现方式。
在这里插入图片描述
在这里插入图片描述
URI和URL都定义了资源是什么，但URL还定义了该如何访问资源。URL是一种具体的URI，它是URI的一个子集，它不仅唯一标识资源，而且还提供了定位该资源的信息。URI 是一种语义上的抽象概念，可以是绝对的，也可以是相对的，而URL则必须提供足够的信息来定位，是绝对的。
只要能唯一标识资源的就是URI，在URI的基础上给出其资源的访问方式的就是URL

以上还理解不了，看下面这个按例，然后继续看上面的内容
在这里插入图片描述

博址推荐

Swagger简明教程

SpringBoot集成Swagger

1、新建SpringBoot项目，导入swagger依赖

IDEA建立一个SpringBoot Web工程
在这里插入图片描述

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

 <!--swagger依赖-->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version>
</dependency>
<!--swagger ui-->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>

如果是3.0直接导入下面一个依赖即可
在这里插入图片描述

2、编写swagger的配置文件
在这里插入图片描述
当然了你可以配置一下 Swagger信息可参考如下
配置原理请参考此视频

@Configuration
@EnableSwagger2
public class Swagger2Config {/*** 创建API应用* apiInfo() 增加API相关信息* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，* 指定扫描的包路径来定义指定要建立API的目录。* @return*/@Beanpublic Docket coreApiConfig(){return new Docket(DocumentationType.SWAGGER_2).apiInfo(adminApiInfo()).groupName("adminApi").select()//只显示admin下面的路径.paths(Predicates.and(PathSelectors.regex("/admin/.*"))).build();}private ApiInfo adminApiInfo(){return new ApiInfoBuilder().title("尚融宝后台管理系统--api文档").description("尚融宝后台管理系统接口描述").version("1.0")//作者信息.contact(new Contact("李燕茹","http://baidu.com","728831102@qq.com")).build();}
}

编写一个hello工程
在这里插入图片描述

启动项目 测试运行：http://localhost:8080/swagger-ui.html
在这里插入图片描述
为什么访问此路径可以出现这个页面，这个页面哪来的

在这里插入图片描述

Swagger配置Swagger部分信息及效果
在这里插入图片描述
在这里插入图片描述

Swaggeri配置扫描接口

这块感兴趣可参考视频
在这里插入图片描述

配置是否启动Swagger
在这里插入图片描述
我只希望我的Swagger在生产环境中使用，在发布的时候不使用？
. 判断是不是生产环境flag=false
. 注入enable(flag)

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

配置API文档的分组
（groupName可以进行分组以区分后端开发者，如果有多个后端开发者，可以在Swagger2Config类里写多个Docket对象然后通过@Bean注入，不同的Docket对象代表不同的分组）

在这里插入图片描述
如何配置多个分组：多个Docket实例即可

为什么要分组：实际工作多人开发(系统协作开发)，Bean可能来自很多类，最终都得被Spring托管，你写的Bean是管你的扫描的，别人写的Bean是管别人扫描的。
每个人(一个个Bean)扫描自己的包，对别人没影响
在这里插入图片描述
在这里插入图片描述

实体类信息的配置
在这里插入图片描述
在这里插入图片描述
这样是没有注释的，不太清楚每个字段含义，如何加上实体类的相关注释呢
在这里插入图片描述
在这里插入图片描述
在这里插入图片描述
给接口方法、参数加注释
在这里插入图片描述

Swagger常用注解

更详细的说明请参见官方注解说明文档
Swagger常用注解1
swagger常用注解2

1、@ApiModel
使用场景：在实体类上使用，标记类时swagger的解析类
概述：提供有关swagger模型的其它信息，类将在操作中用作类型时自动内省

2、@ApiModelProperty
使用场景：使用在被 @ApiModel 注解的模型类的属性上。表示对model属性的说明或者数据操作更改
概述：添加和操作模型属性的数据

 /*** Student类 学生实体类
*/
@ApiModel(value = "Student",description = "用户实体类")
public class Student implements Serializable {@ApiModelProperty(value = "学号")private Integer id; //学号@ApiModelProperty(value = "姓名")private String name; //姓名//日期的格式 年-月-日@ApiModelProperty(value = "生日")@DateTimeFormat(pattern = "yyyy-MM-dd")private Date birthday; //生日}

3、@ApiOperation
使用场景：使用在方法上，表示一个http请求的操作
概述：用来表示Controller类下的http请求方法

 @ApiOperation("添加学生信息")@PostMapping(value = "/student")public void AddStudent(Student student) {studentService.AddStudent(student);}

4、@ApiParam
使用场景：在 Rest 接口上或 Rest 接口参数前边使用
概述：为 Rest 接口参数添加其它元数据(导入到 yapi 中不会被解析)

 @ApiOperation("判断验证码是否正确")@RequestMapping(value = "/UpdatePassword" , method = RequestMethod.POST)public CommonResult updatePassword(@ApiParam(value = "手机号码"，required = true) @RequestParam String userPhone,@ApiParam(value = "验证码",required = true) @RequestParam String authCode){return userMemberService.updatePassword(userPhone,authCode);}

@Api：修饰整个类，描述Controller的作用

@ApiOperation：描述一个类的一个方法，或者说一个接口

@ApiParam：单个参数描述

@ApiModel：用对象来接收参数

@ApiProperty：用对象接收参数时，描述对象的一个字段

@ApiResponse：HTTP响应其中1个描述

@ApiResponses：HTTP响应整体描述

@ApiIgnore：使用该注解忽略这个API

@ApiError ：发生错误返回的信息

@ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值

@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

mplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值

@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表
在这里插入图片描述

Swagger增强工具knife4j

knife4j官方文档
在这里插入图片描述
Spring Boot 基础教程：集成 Knife4j
swagger文档增强工具knife4j使用详解

先说一下引入这个依赖我们都能干嘛
Swagger 功能增强：接口搜索、离线文档下载、全局参数设置等功能…
①可以搜索接口名称快速定位接口(搜索功能)
②可以下载markdown、HTML、word 等格式文件(下载功能)
③。。。。。。自己去发现，更多详情戳我

在这里插入图片描述
①引入依赖 你可以去maven官网搜knife4j 我这里是springboot项目
在这里插入图片描述

注意：引入knife4j后会自动引入swagger相关依赖，所以无需再手动引入swagger相关依赖，否则会引起版本冲突，在使用knife4j的一些增强功能时会报错

<!-- knife4j接口文档 -->
<!-- <dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.6.1</version>
</dependency>-->
<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter -->
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>2.0.2</version>
</dependency>

②添加SwaggerConfiguration作为Swagger2的配置类
这块就是我上面配置文件的基础上在加点注解啥的
关于这块配置类上的注解网上都不太一样，我也没此需求，也没验证，后期遇到我在更新。
需要的伙伴自行百度，能弄成效果即可
（解决SpringBoot使用knife4j无法引入@EnableSwagger2WebMvc：之前已经引入过了swagger2了，再引入Knife4j就会导致注解无法引入，把原来swagger2的东西注释掉后，这个注解就能正常引入了。）
(Knife4j 2.0.7默认引入swagger2.10.5,而swagger2.1版本开始引入了@EnableSwagger2WebMvc,废弃了@EnableSwagger2)

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;/*** @类名: SwaggerConfiguration* @包名: com.blogs.web.blogsweb.config* @IDE的名称: IntelliJ IDEA* @当前项目的名称: blogsweb* @作者: YangMian* @时间: 2020/5/12 14:31* @版本: 1.0.0* <p>说明: </p>*/
@Configuration
@EnableSwagger2
@EnableKnife4j
//@EnableSwagger2WebMvc 有用这个注解的 
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2)      // 选择swagger2版本.apiInfo(apiInfo())         //定义api文档汇总信息.select().apis(RequestHandlerSelectors.basePackage("com.blogsweb.web"))  // 指定生成api文档的包.paths(PathSelectors.any())     // 指定所有路径.build();}/*** 构建文档api信息** @return*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title("")     // 文档标题.contact(new Contact("", "", ""))   //联系人信息.description("")      //描述.version("1.0.1")     //文档版本号.termsOfServiceUrl("")     //网站地址.build();}
}

当然了你也可以先不做任何配置 输入localhost:8080/doc.html进入如下页面

在这里插入图片描述

详细网址
在这里插入图片描述

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


http://chatgpt.dhexx.cn/article/DRweoXAu.shtml

相关文章

JVM快速入门（类加载，对象创建，运行数据区，GC垃圾回收算法，jvm调优）

JVM快速入门（类加载，对象创建，运行数据区，GC垃圾回收算法，jvm调优）

JVM快速入门 JVM定义&#xff1a;常见的几种jvmJDK&#xff0c;JRE&#xff0c;JVM区别 类加载过程类加载器作用加载器分类双亲委派机制好处 全盘委托机制 对象的创建流程类加载校验分配内存设置初值设置对象头对象头中的Mark Word 字段&#xff08;32位&#xff09;对象头中的…
阅读更多...
一起学JVM（GC可视化工具Visual GC）

一起学JVM（GC可视化工具Visual GC）

导读 众所周知&#xff0c;JVM&#xff08;java虚拟机&#xff09;运行着我们的java程序。java本身提供了自带工具VisualVM来帮助我们查看JVM的运行情况&#xff0c;下面主要介绍GC的可视化插件&#xff0d;Visual GC java版本 1.8.0_281 工具 VisualVM　的　Visual GC　插…
阅读更多...
JVM G1详解

JVM G1详解

java程序性能 当我们调优java程序时&#xff0c;通常的目标有两个&#xff1a; 响应能力 或者 吞吐量 响应能力 响应能力指一个程序或者系统对请求的是否能够及时响应。 比如&#xff1a; 一个桌面UI能多快的响应一个事件&#xff1b; 一个网站能够多快返回一个页面请求&…
阅读更多...
最简单的JVM内存结构图

最简单的JVM内存结构图

目录 JVM内存结构图 方法区 堆 栈 程序计数器 本地方法栈 直接内存 内存分配性能优化-逃逸分析 总结 JVM内存结构图 大家好&#xff0c;好几天没有更新了&#xff0c;今天的内容有点多&#xff0c;我们详细介绍下JVM内部结构图&#xff0c;还是和之前一样&#xff0c;案…
阅读更多...
JVM进阶(十一)：JAVA G1收集器

JVM进阶(十一)：JAVA G1收集器

文章目录 一、前言 一、前言 G1(Garbage First)垃圾收集器是当今垃圾回收技术最前沿的成果之一。早在JDK7就已加入JVM的收集器大家庭中&#xff0c;成为HotSpot重点发展的垃圾回收技术。同优秀的CMS垃圾回收器一样&#xff0c;G1也是关注最小时延的垃圾回收器&#xff0c;也同…
阅读更多...
JVM监控之图形化工具

JVM监控之图形化工具

一、工具概述 使用命令行工具存在以下的局限性&#xff1a; 无法获取方法级别的分析数据&#xff0c;如方法之间的调用关系、各方法的调用次数和调用时间等要去用户登陆到java应用所在的宿主机上分析数据通过终端输出&#xff0c;结构不够直观 随着java应用的官方使用&#…
阅读更多...
Java 知识结构图

Java 知识结构图

简介 《 值得去的地方&#xff0c;没有捷径&#xff1b;难走的路才更值得开始 》 为什么要说这个【知识结构图】呢&#xff0c;其实是针对于刚开始学习&#xff0c;工作或工作一段时间的人&#xff0c;每天忙&#xff0c;杂七杂八&#xff0c;自己身心巨累&#xff0c;又想要偷…
阅读更多...
Java程序员必备基础结构图

Java程序员必备基础结构图

前言 最近看了深入理解Java虚拟机第三版&#xff0c;整理了一些基础结构图&#xff0c;算是比较全的了&#xff0c;做一下笔记&#xff0c;大家一起学习。 1.Java虚拟机运行时数据区图 JVM内存结构是Java程序员必须掌握的基础。 程序计数器 程序计数器&#xff0c;可以看作…
阅读更多...
JVM 结构图

JVM 结构图

一&#xff1a;Java技术体系模块图 二&#xff1a;JVM内存区域模型 1.方法区 也称"永久代” 、“非堆”&#xff0c; 它用于存储虚拟机加载的类信息、常量、静态变量、是各个线程共享的内存区域。默认最小值为16MB&#xff0c;最大值为64MB&#xff0c;可以通过-XX:Per…
阅读更多...
JVM结构、GC工作机制详解

JVM结构、GC工作机制详解

题外话&#xff1a;最近在应聘阿里2015暑期实习&#xff0c;感触颇多。机会总是留给有准备的人的&#xff0c;所以平常一定要注意知识的巩固和积累。知识的深度也要有一定的理解&#xff0c;不比别人知道的多&#xff0c;公司干嘛选你&#xff1f;关于JVM和GC&#xff0c;我相信…
阅读更多...
详解 JVM Garbage First(G1) 垃圾收集器

详解 JVM Garbage First(G1) 垃圾收集器

前言 Garbage First(G1)是垃圾收集领域的最新成果，同时也是HotSpot在JVM上力推的垃圾收集器，并赋予取代CMS的使命。如果使用Java 8/9，那么有很大可能希望对G1收集器进行评估。本文详细首先对JVM其他的垃圾收集器进行总结，并与G1进行了简单的对比；然后通过G1的内存模型、G1…
阅读更多...
【JVM】JVM内存结构之——G1收集器

【JVM】JVM内存结构之——G1收集器

目录 1. 什么是G12. G1收集器发展历程3. G1收集器分区划分3.1 为什么G1收集器需要设计巨型对象3.2 G1收集器参数设置 3.3 G1收集器回收的细节3.4 G1收集器Rset问题&#xff08;记忆集&#xff09;3.5 G1两种回收策略4. G1收集器优缺点 5. G1收集器核心配置参数 1. 什么是G1 G1…
阅读更多...
Visual Studio C# WinForm开发入门(5)：TabControl 控件使用

Visual Studio C# WinForm开发入门(5)：TabControl 控件使用

TabContrl选项卡控件可创建标签化窗口&#xff0c;在实际 编程中经常用到&#xff0c;该控件的作用是将相关的组件组合到一系列选项卡页面上。 比如下面的例子&#xff0c;在tabPage1页面和tabPage2页面各放了2个checkBox控件&#xff0c;通过点击不同page即可切换&#xff1a;…
阅读更多...
WPF自定义TabControl样式

WPF自定义TabControl样式

WPF自定义TabControl样式 原文: WPF自定义TabControl样式 WPF自定义TabControl&#xff0c;TabControl美化 XAML代码&#xff1a; <TabControl x:Class"SunCreate.Common.Controls.TabControlEx"xmlns"http://schemas.microsoft.com/winfx/2006/xaml/present…
阅读更多...
C# WinForm TabControl美化

C# WinForm TabControl美化

窗口Load加下面代码&#xff0c;ItemSize根据自己显示文本长度调整 #region tabMainItem属性设置this.tabModuleMainItem.DrawMode TabDrawMode.OwnerDrawFixed;this.tabModuleMainItem.Alignment TabAlignment.Top;this.tabModuleMainItem.SizeMode TabSizeMode.Fixed;this…
阅读更多...
浅谈C#tabcontrol应用

浅谈C#tabcontrol应用

作为Winfrom开发者来说&#xff0c;我们很多时候会用到tabcontrol来实现和网页标签页相关的效果。同时微软自带的控件样式不符合我们的需求&#xff0c;我们该如何去实现更加美观且可以自定义的组合控件呢&#xff1f;带着这个问题进入我们今天的主题&#xff0c;组合控件tabco…
阅读更多...
C# WPF TabControl控件用法详解

C# WPF TabControl控件用法详解

概述 TabControl我之前有讲过一节&#xff0c;内容详见&#xff1a; C# WPF TabControl用法指南(精品)&#xff0c;上节主要讲解了tabcontrol控件的左右翻页&#xff0c;以及页面筛选&#xff0c;以及数据绑定等内容&#xff0c;这节内容继续接续上节内容进行扩展讲解&#xff…
阅读更多...
WPF 自定义控件TabControl

WPF 自定义控件TabControl

WPF 自定义控件TabControl 新TabControl效果&#xff1a; 新添加一个自定义控件ZTabControl&#xff1a; public class ZTabControl : TabControl{#region Private属性#endregion#region 依赖属性定义public static readonly DependencyProperty TypeProperty;#endregion#r…
阅读更多...
Winform TabControl标签美化

Winform TabControl标签美化

前期工作&#xff1a; 加载资源文件&#xff0c;双击“Resources.resx" 类型选择Images 【添加资源】——【添加现有文件】 选择需要添加的图片文件&#xff0c;保存即可。 在下面的资源文件夹中即可看到添加的图片列表 **方法一&#xff1a;**重绘标签及背景 新建窗体…
阅读更多...
WPF 自定义TabControl控件样式（转）

WPF 自定义TabControl控件样式（转）

WPF 自定义TabControl控件样式 一、前言 程序中经常会用到TabControl控件&#xff0c;默认的控件样式很普通。而且样式或功能不一定符合我们的要求。比如&#xff1a;我们需要TabControl的标题能够居中、或平均分布&#xff1b;或者我们希望TabControl的标题能够进行关闭。要…
阅读更多...
推荐文章

Copyright @ 2022~2023