Java的Mvc整合Swagger的knife4框架

Swagger的介绍

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。使用Swagger,就是把相关的信息存储在它定义的描述文件里面(yml或json格式),再通过维护这个描述 文件可以去更新接口文档,以及生成各端代码。而Springfox-swagger,则可以通过扫描代码去生成这个 描述文件,连描述文件都不需要再去维护了。所有的信息,都在代码里面了。代码即接口文档,接口文档即代码。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型 紧密集成到服务器端的代码,允许API来始终保持同步。

swagger的主要作用

Swagger最主要的作用就是接口文档的在线自动生成和功能测试,也就是测试我们开发的功能是否可用。

Swagger的使用

如果直接使用Swagger是非常麻烦的,应为需要使用Swagger其实就是在编写一个json文件,这个是十分的繁琐的一道过程。所以一般是使用的java的mvc集成Swagger的框架增强的解决方案knife4它的底层是由Swagger组成的但是使用起来是相对比较简单的。

1.导入依赖

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-spring-boot-starter</artifactId><version>3.0.2</version>
</dependency>

2.导入knife4相关的配置类

@EnableSwagger2
@EnableKnife4j//与上面的注解表示开启了Swagger文档功能
@Configuration//声明为配置类
public class WebMvcConfig extends WebMvcConfigurationSupport {//mvc静态资源的映射类
//创建api接收文档
@Bean
public Docket createRestApi(){return  new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("你的controller包在项目中的位置")).paths(PathSelectors.any()).build();
}
​
//api的接口文档的模板
private ApiInfo apiInfo(){return new ApiInfoBuilder().title("标题").version("版本号").description("描述的信息").build();}
}

上面第一个方法的返回值docket是文档的意思,通过这个对象来具体描述文档的信息,需要注意.apis(RequestHandlerSelectors.basePackage())这里面需要项目中的controller的包的位置,因为前段发送请求是发送进入的controller中的某个方法上面,所以需要来扫描每一个方法,最终映射成一个接口。然让其生成出对于的接口文档

3.设置静态资源的映射

设置这个的原因是需要让接口文档页面可以被访问。

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}

doc.html这个页面并不需要我们自己写,而是有框架帮助我们自动生成的。

4.在你的拦截器设置不需要进行处理的路径

配置好后需要在你的拦截器上面对于接口文档的路径。

"/doc.html",
"/webjars/",
"/swagger-resources",
"/v2/api-docs"

如果并不想要设计的话,可以先进行登录之后可以直接进行访问。

Swagger效果展示

添加后成功的效果如图显示

我们可以从上获取到诸多信息,如作版本、host、basePaht、分租Url等信息。 这些信息都是我们之前添加在kinfe4中的apiInfo方法中所设置的信息。我们可以看到所统计的接口信息,比如post、put、delete、get等接口d的数量

具体可以看我们的左侧的信息展示,可以清晰的看见我们每一个的controller类里面的接口具体有多少个,可以非常清晰的展示在我们页面上。

我们选择一个点开看可以将我们每一个方法的方法名和请求类型都展示在页面上给我吗后端开发人员进行查看。

我们选择一个方法点开查看,可以清晰的看见我们该方法的参数名称和我们该参数的类型,比如我们参数的请求示例、响应数据类型等信息。我们的参数在下面也可以获取到这个参数是否是必须需要的。

继续往下翻找可以看的这个方法的响应状态、响应参数、响应示例等信息。我们可以从响应示例看出我们的具体响应是什么样子的方便我们使用。

我们点击调用可以看见我们的请求所需要的参数,可以进行输入参数也可以点击发送,也可以直接点击发送。

这里可以看见我们的请求已经返回了,这里是已经登陆的情况,如果并没有登录会在msg里面返回一个NOTLOGIN。

我们不仅可以通过knife4自动生成接口文档,给我们后端开发人员使用来进行测试,还有可以将我们这个生成的文档导出。

我们点击这个文档管理下面的离线文档,可以在右侧显示中看见它为我们提供了4种下载方式Html、Markdown、Word、OpenAPI。

我们选择Markdown下载模式可以看见它已经为我们下载好了。我们点开刚刚下载好的文档查看。

可以看见我们已经是提供好了我们整个项目的api文档,如果你选择的是Openapi的下载方式那么下载出的格式是json类型。

在左侧的Swagger Models里面有着我们整个项目的数据模型模型,每一个类点开之后属性都会展示出来,给我们可以快速且方便的查询。

Swagger的常用注解

1.@Api

这个主要用在请求类,例如Controller,表示对于类的说明。

使用方式:@Api(value = "/user", description = "Operations about user")

它表示数据是user类型的,

  • value:这是类的路径,将在生成的 Swagger 文档中显示。

  • description:这是对数据来源的描述,也将在生成的 Swagger 文档中显示

2.@ApiModel

通常使用在实体类上,表示返回响应数据的信息。

@ApiModel(value = "UserModel", description = "A model representing a user")

这个表示来自于user类,它提供了两个属性

  • value:这是模型的名称,将在生成的 Swagger 文档中显示。

  • description:这是对模型的描述,也将在生成的 Swagger 文档中显示

3.@ApiModelProperty

这个注解则用于类中的字段,并为它们提供了额外的元数据,如字段的描述和是否必需等。通过使用这些注解,你可以更容易地为你的 RESTful Web 服务生成和维护 API 文档,它的属性有:

value:字段说明 name:重写属性名字 dataType:重写属性类型 required:是否必填(true为必填) example:举例说明 hidden:隐藏(true为隐藏)

例如: @ApiModelProperty(value = "值",required = true/false,name="属性名",example="说明")

4.‌@ApiOperation

主要使用于方法表示一个http请求的操作,方法如下:

@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”)

value:对该操作进行简单的描述,尽量控制在120字符以内。 notes:对操作的详细描述。 httpMethod:指定操作使用的HTTP方法类型,可选值 “GET”、“HEAD”、“POST”、“PUT”、“DELETE”、“OPTIONS”和“PATCH”。 tags:用来给操作打标签,Swagger UI 将在操作列表下面展示 tag 列表,每个 tag 下面展示拥有该 tag 的操作列表。(就是分组)

5.‌@ApiImplicitParam

作用在方法上,表示单独的请求参数它的属性有:

1.name :参数名。

2.value : 参数的具体意义,作用。

3.required : 参数是否必填。

4.dataType :参数的数据类型。

5.paramType :查询参数类型,这里有几种形式

类型的作用:

path 以地址的形式提交数据 query 直接跟参数完成自动映射赋值 body 以流的形式提交 仅支持POST header 参数在request headers 里边提交 form 以form表单的形式提交 仅支持POST

6.‌@ApiImplicitParams

使用在请求方法上面,表示接受多个@ApiImplicitParam参数

Swagger常用接口的使用

1.@ApiModel和@ApiModelProperty的用法

选择一个实体类使用上面的@ApiModel和@ApiModelProperty注解,运行后在doc.html里面查看我们的结果。

可以清晰看到的看见我们之前的setmeal类已经改名为套餐,也就是我们在@APIModel里面设置的名称,并且点开这个类已经可以看的我们的属性里面有说明,它的话是我们在@ApiModelProperty里面设置的说明。

2.@Api和@ApiOperation的用法

将我们的上面的@Api和@ApiOperation添加到我们的controller也就是请求方法上面。保存进行运行再次到doc.html里面查看我们这个controller类有什么变化。

可以看见我们doc.html页面上的左侧已经进行了更新,上面显示的接口名不再是类名而是我们在@Api里面输入的名称,并且方法名也是我们在@ApiOperation里面所输入的名称。

3.@ApiImplicitParam和@ApiImplicitParams的用法

我们使用了ApiImplicitParams将多个ApiImplicitParam包裹起来,每一个ApiImplicitParam里面都是我们方法所需要的一个参数,并标明其名称和意义以及是否是必须要传递的参数等信息

已经可以看到我们的参数的一些说明和信息,也就是我们在ApiImplicitParam所包含的参数里面给其添加的信息,这也更加方便我们开发时对于项目的检查和理解。

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

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

相关文章

01_Node.js入门 (黑马)

01_Node.js入门 知识点自测 从 index.js 出发&#xff0c;访问到 student/data.json 的相对路径如何写? A&#xff1a;../public/teacher/data.json B&#xff1a;./public/student/data.json C&#xff1a;../student/data.json <details><summary>答案</sum…

2024.12.5——攻防世界Training-WWW-Robots攻防世界baby_web

2024.12.5—攻防世界Training-WWW-Robots 知识点&#xff1a;robots协议 dirsearch工具 本题与第一道Robots协议十分类似&#xff0c;不做wp解析 大致步骤&#xff1a; step 1 打开靶机&#xff0c;发现是robots协议相关 step 2 用dirsearch进行扫描目录 step 3 url传参r…

电脑无法识别usb设备怎么办?电脑无法识别usb解决方法

usb设备是我们常解除的外部操作以及存储设备&#xff0c;它可以方便用户数据传输以及操作输入。但在使用过程中&#xff0c;大家基本都碰到过电脑无法识别usb设备这种情况。这种情况下&#xff0c;我们应该怎么办呢&#xff1f;下面将为你介绍几种可能的原因和解决方法&#xf…

【学习总结|DAY014】Java面向对象高级-继承、多态

一、继承&#xff08;Inheritance&#xff09; 1. 概述 继承是面向对象编程的一种特性&#xff0c;允许我们定义一个类&#xff08;称为子类或派生类&#xff09;以继承另一个类&#xff08;称为超类或基类&#xff09;的功能。 2. 语法格式 public class Zi extends Fu {/…

筑起厂区安全--叉车安全防护装置全解析

在繁忙的工业生产领域中&#xff0c;叉车作为搬运工&#xff0c;穿梭于仓储与生产线之间。然而&#xff0c;叉车的高效运作背后&#xff0c;也隐藏着诸多安全风险&#xff0c;尤其是在那些空间狭小、物流繁忙的环境中。为了降低这些潜在的危险&#xff0c;叉车安全防护装置便成…

MS SQL SERVER服务自动停止解决

报错原因 电脑异常重启&#xff0c;导致 MS SQL server 服务启动后自动停止&#xff0c;在【计算机管理】-【事件查看器】-【windows日志】中进行查看系统错误日志&#xff0c;在【应用程序】下发现可能的错误信息&#xff1a; 传递给数据库 ‘model’ 中的日志扫描操作的日志…

网络安全信息收集(总结)更新

目录 重点&#xff1a; 前言&#xff1a; 又学到了&#xff0c;就是我们什么时候要子域名收集&#xff0c;什么时候收集域名&#xff0c;重点应该放前面 思考&#xff1a; 信息收集分为哪几类&#xff0c;什么是主域名&#xff0c;为什么要收集主域名&#xff0c;为什么要收…

使用 Postman 上传二进制类型的图片到后端接口写法

我们有的时候会有需求&#xff0c;就是通过 postman 传递二进制图片到后端接口&#xff0c;如下图&#xff1a; 那我们的 Java 接口需要怎么写呢&#xff1f; Spring Boot 接收这些数据的方式需要使用 RequestBody 注解来处理原始的二进制数据&#xff08;byte[]&#xff09;。…

Java Web 7 请求响应(Postman)

前言&#xff08;SpringBoot程序请求响应流程&#xff09; 以上一章的程序为例&#xff0c;一个基于SpringBoot的方式开发一个web应用&#xff0c;浏览器发起请求 /hello 后 &#xff0c;给浏览器返回字符串 “Hello World ~”。 而我们在开发web程序时呢&#xff0c;定义了一…

pytorch多GPU训练教程

pytorch多GPU训练教程 文章目录 pytorch多GPU训练教程1. Torch 的两种并行化模型封装1.1 DataParallel1.2 DistributedDataParallel 2. 多GPU训练的三种架构组织方式2.2 数据不拆分&#xff0c;模型拆分&#xff08;Model Parallelism&#xff09;2.3 数据拆分&#xff0c;模型…

【opencv入门教程】9.视频加载

文章选自&#xff1a; 一、VideoCapture类 用于从视频文件、图像序列或摄像头捕获视频的类。函数&#xff1a;CV_WRAP VideoCapture();brief 默认构造函数CV_WRAP explicit VideoCapture(const String& filename, int apiPreference CAP_ANY);brief 使用 API 首选项打开…

海外的bug-hunters,不一样的403bypass

一种绕过403的新技术&#xff0c;跟大家分享一下。研究HTTP协议已经有一段时间了。发现HTTP协议的1.0版本可以绕过403。于是开始对lyncdiscover.microsoft.com域做FUZZ并且发现了几个403Forbidden的文件。 &#xff08;访问fsip.svc为403&#xff09; 在经过尝试后&#xff0…

阿里内部正式开源“Spring Cloud Alibaba (全彩小册)”

年轻的毕业生们满怀希望与忐忑&#xff0c;去寻找、竞争一个工作机会。已经在职的开发同学&#xff0c;也想通过社会招聘或者内推的时机争取到更好的待遇、更大的平台。 然而&#xff0c;面试人群众多&#xff0c;技术市场却相对冷淡&#xff0c;面试的同学们不得不面临着 1 个…

乘上 SpringBoot 东风,广场舞团掀起律动热潮

2 系统开发环境 2.1 Java技术 Java是由Sun公司推出的一门跨平台的面向对象的程序设计语言。因为Java 技术具有卓越的通用性、高效性、健壮的安全性和平台移植性的特点&#xff0c;而且Java是开源的&#xff0c;拥有全世界最大的开发者专业社群&#xff0c;所以Java的发展迅速。…

【PlantUML系列】状态图(六)

一、状态图的组成部分 状态&#xff1a;对象在其生命周期内可能处于的条件或情形&#xff0c;使用 state "State Name" as Statename 表示。初始状态&#xff1a;表示对象生命周期的开始&#xff0c;使用 [*] 表示。最终状态&#xff1a;表示对象生命周期的结束&…

创建 React Native 项目

创建 React Native 项目 npx react-nativelatest init YourProject切换依赖源 切换好源之后&#xff0c;你需要进入 android 目录&#xff0c;然后运行 gradlew build 命令。 Android 依赖安装是使用 gradlew 进行管理的。 $ cd android $ ./gradlew build --refresh-depend…

Linx下自动化之路:Redis安装包一键安装脚本实现无网极速部署并注册成服务

目录 简介 安装包下载 安装脚本 服务常用命令 简介 通过一键安装脚本实现 Redis 安装包的无网极速部署&#xff0c;并将其成功注册为系统服务&#xff0c;开机自启。 安装包下载 redis-7.0.8.tar.gzhttp://download.redis.io/releases/redis-7.0.8.tar.gz 安装脚本 修…

Meta Llama 3.3 70B:性能卓越且成本效益的新选择

Meta Llama 3.3 70B&#xff1a;性能卓越且成本效益的新选择 引言 在人工智能领域&#xff0c;大型语言模型一直是研究和应用的热点。Meta公司最近发布了其最新的Llama系列模型——Llama 3.3 70B&#xff0c;这是一个具有70亿参数的生成式AI模型&#xff0c;它在性能上与4050…

idea_maven详解

秒懂Maven maven简介maven安装和配置maven本地配置maven工程的GAVP创建maven工程项目结构说明项目构建说明 Maven依赖管理核心信息配置依赖管理配置依赖信息查询依赖范围设置依赖属性配置依赖下载失败错误解决Build构建配置依赖传递依赖冲突 maven工程继承继承作用应用场景继承…

Linux Ubuntu 安装配置RabbitMQ,springboot使用RabbitMQ

rabbit-Ubuntu 一篇文章学会RabbitMQ 在Ubuntu上查看RabbitMQ状态可以通过多种方式进行&#xff0c;包括使用命令行工具和Web管理界面。以下是一些常用的方法&#xff1a; 1-使用systemctl命令&#xff1a; sudo systemctl start rabbitmq-server sudo systemctl status ra…