Swagger2之SpringBoot集成使用

前言:

      我们对于Mybatis-Plus的分享较多,都是接触的一些数据库相关的知识,今天给大家带来的是Swagger2

Swagger2

1.介绍:

Swagger2是一个规范和完整的框架,用于生成、描述、调用和可视化Restful风格的web服务,现在我们使用spring boot 整合它。作用:

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

2.特点:

在线 API 文档可视化:

Swagger2 提供了一个基于 Web 的可视化界面,使得开发人员和其他团队成员能够轻松查看和理解 API 的结构和功能。这个界面允许用户直接在浏览器中测试 API,了解每个接口的请求和响应格式,并提供了交互式的方式来探索和理解 API 的功能。
功能测试:

Swagger2 不仅提供了 API 文档的生成和可视化,还可以通过界面上提供的测试功能进行功能测试。开发人员可以在 Swagger2 的界面上直接调用 API 接口,观察返回结果,确保每个接口按照预期工作。这样可以在开发阶段及时发现和修复问题。
与 Spring Boot 整合:

Swagger2 可以很容易地与 Spring Boot 集成。通过添加相应的依赖和配置,Swagger2 可以自动扫描项目中的 API,并生成相应的文档。Spring Boot 的注解与 Swagger2 的注解可以很好地配合,使得整合变得非常简单。
 

3.常用注解

注解描述
@Api将类标记为 Swagger 资源。
@ApiImplicitParam表示 API 操作中的单个参数。
@ApiImplicitParams允许多个 ApiImplicitParam 对象列表的包装器。
@ApiModel提供有关 Swagger 模型的其他信息。
@ApiModelProperty添加和操作模型属性的数据。
@ApiOperation描述针对特定路径的操作或通常是 HTTP 方法。
@ApiParam为操作参数添加额外的元数据。
@ApiResponse描述操作的可能响应。
@ApiResponses允许多个 ApiResponse 对象列表的包装器。
@Authorization声明要在资源或操作上使用的授权方案。
@AuthorizationScope描述 OAuth2 授权范围。

三、SpringBoot整合Swagger2

1. 导入pom依赖

 <dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.8.5</version></dependency><!-- 使用1.5.22--><dependency><groupId>io.swagger</groupId><artifactId>swagger-models</artifactId><version>1.5.22</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version><exclusions><exclusion><artifactId>swagger-models</artifactId><groupId>io.swagger</groupId></exclusion></exclusions></dependency>

2. 引入配置类

(这是用于)

 Swagger2Configuration.java

介绍:

package com.lya.springbootmybatisplus.config;import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
//@Profile({"dev", "test"})  dev(开发)、test(测试)、prod(生产)
public class Swagger2Configuration extends WebMvcConfigurationSupport {/*** 创建该API的基本信息  http://项目实际地址/doc.html*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title("SpringBoot集成Swagger2").description("测试系统").termsOfServiceUrl("https://www.baidu.com").version("1.0.0").build();}/*** 创建API应用*/@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.zking.boot.controller")).paths(PathSelectors.any()).build();}@Overrideprotected void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}}

2.2、数据回显格式

JsonResponseBody.java
package com.lya.springbootmybatisplus.resp;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;@Data
@ApiModel("响应对象")
public class JsonResponseBody<T> {@ApiModelProperty("响应码")private Integer code;@ApiModelProperty("响应信息")private String msg;@ApiModelProperty("响应数据")private T data;@ApiModelProperty("响应条数(用于分页)")private Long total;private JsonResponseBody(JsonResponseStatus jsonResponseStatus, T data) {this.code = jsonResponseStatus.getCode();this.msg = jsonResponseStatus.getMsg();this.data = data;}private JsonResponseBody(JsonResponseStatus jsonResponseStatus, T data, Long total) {this.code = jsonResponseStatus.getCode();this.msg = jsonResponseStatus.getMsg();this.data = data;this.total = total;}public static <T> JsonResponseBody<T> success() {return new JsonResponseBody<T>(JsonResponseStatus.OK, null);}public static <T> JsonResponseBody<T> success(T data) {return new JsonResponseBody<T>(JsonResponseStatus.OK, data);}public static <T> JsonResponseBody<T> success(T data, Long total) {return new JsonResponseBody<T>(JsonResponseStatus.OK, data, total);}public static <T> JsonResponseBody<T> unknown() {return new JsonResponseBody<T>(JsonResponseStatus.UN_KNOWN, null);}public static <T> JsonResponseBody<T> other(JsonResponseStatus jsonResponseStatus) {return new JsonResponseBody<T>(jsonResponseStatus, null);}}

JsonResponseStatus.java

package com.lya.springbootmybatisplus.resp;import lombok.Getter;@Getter
public enum JsonResponseStatus {OK(200, "OK"),UN_KNOWN(500, "未知错误"),RESULT_EMPTY(1000, "查询结果为空!"),;private final Integer code;private final String msg;JsonResponseStatus(Integer code, String msg) {this.code = code;this.msg = msg;}}

3. 初步的访问swagger网址

        启动项目,项目默认访问路径+/doc.html即可

4. 第三方工具引入接口 

放入这个地址:

localhost:8080/v2/api-docs

就会加载项目:

四、swagger基本使用

@Api

@Api注解用在类上,说明该类的作用。可以标记一个Controller类做为swagger文档资源。

属性说明
valueurl的路径值
tags如果设置这个值、value的值会被覆盖
produces返回的格式类型例如:"application/json, application/xml"
consumes接收请求参数的类型例如:"application/json, application/xml"
protocolsPossible values: http, https, ws, wss.
authorizations高级特性认证时配置

案例演示

@RestController
@Api(value = "书本管理",tags = {"书本管理"}) //tags可以代替value属性
@RequestMapping("/book")
public class BookController {...
}

@ApiOperation

@ApiOperation注解用在方法上,说明方法的作用,每一个url资源的定义。

属性说明
valueurl的路径值
tags如果设置这个值、value的值会被覆盖
produces返回的格式类型例如:"application/json, application/xml"
consumes接收请求参数的类型例如:"application/json, application/xml"
hidden是否在文档中显示
notes注释说明
response返回的对象
responseContainer这些对象是有效的 "List", "Set" or "Map".,其他无效
responseReference指定对响应类型的引用。指定的引用可以是本地的,也可以是远程的*将按原样使用,并覆盖任何指定的response()类
responseHeaders响应旁边提供的可能标题列表
httpMethod"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
codehttp的状态码 默认 200

案例演示

@ApiOperation(value = "查询所有书本信息", notes = "查询返回所有书本信息集合",produces = "application/json")
@GetMapping(value="/queryAll")
public JsonResponseBody<List<Book>> queryAll(){try {return bookService.queryAll();} catch (Exception e) {e.printStackTrace();return new JsonResponseBody<>(500,e.getMessage());}
}

@ApiImplicitParam

@ApilmplicitParam 注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入;

属性说明
paramType参数放在哪个地方
name参数名称
value参数代表的含义
dataType参数类型
dataTypeClass参数类型
required是否必要
defaultValue参数的默认值

paramType

类型作用
path以地址的形式提交数据,用于restful接口。请求参数采用@PathVariable获取
query直接跟参数完成自动映射赋值。请求参数可采用@RequestParam获取
body以流的形式提交,仅支持POST。请求参数采用@RequestBody获取
header参数在request headers里边提交。请求参数采用@RequestHeader获取
form以form表单的形式提交,仅支持POST。

案例演示

@ApiOperation(value="查询单个书本信息",notes = "查询单个书本信息")
@ApiImplicitParam(value="书本ID",name="bookid",required = true,dataType = "String",defaultValue = "8f46b5018a6811e9a9c528d24413c293" )
@GetMapping("/querySingleBook")
public Book querySingleBook(String bookid){JsonResponseBody<Book> json = bookService.selectByPrimaryKey(bookid);return json.getData();
}

@ApiImplicitParams

@ApilmplicitParams 如果有多个参数,则需要使用多个 @ApilmplicitParam 注解来描述, 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中;

案例演示

@ApiOperation(value = "新增书本信息", notes = "新增书本信息",produces = "application/json",consumes = "application/json")
@ApiImplicitParams({@ApiImplicitParam(name="bookname",value="书本名称",required = true,dataType = "String"),@ApiImplicitParam(name="price",value="书本价格",required = true,dataType = "Double"),@ApiImplicitParam(name="booktype",value="书本类型",required = true,dataType = "String")
})
@PostMapping("/addBook")
public JsonResponseBody<?> addBook(@RequestParam String bookname,@RequestParam Double price,@RequestParam String booktype){return bookService.insert(Book.builder().bookid(UUID.randomUUID().toString().replace("-","")).bookname(bookname).booktype(booktype).price(price).build());
}

@ApiModel和@ApiModelProperty

@ApiModel注解描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用 @ApiImplicitParam注解进行描述的时候;

@ApiModelProperty注解描述一个model的属性。

属性说明
value字段说明
name参数名称
dataType参数类型
hidden在文档中隐藏
required是否必要
example举例说明
notes注释说明

案例演示

Controller

@ApiOperation(value="修改书本信息",notes = "修改书本信息")
@PostMapping("/editBook")
public JsonResponseBody<?> editBook(@RequestBody Book book){return bookService.updateByPrimaryKey(book);
}

注意:在这里可以不使用@ApiImplicitParam标注Swagger中的参数信息,因为在这里的输入参数是实体对象,而在实体对象中已经使用@ApiModel和@ApiModelProperty注解进行了标识。

Book实体类

@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value="书本对象")
public class Book implements Serializable {
​/*** 书本编号*/@ApiModelProperty(value="书本编号")private String bookid;
​/*** 书本名称*/@ApiModelProperty(value="书本名称")private String bookname;
​/*** 书本价格*/@ApiModelProperty(value="书本价格")private Double price;
​/*** 书本类型*/@ApiModelProperty(value="书本类型")private String booktype;
​private static final long serialVersionUID = 1L;
}

package com.lya.springbootmybatisplus.pojo;import com.baomidou.mybatisplus.annotation.*;import java.io.Serializable;import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import jdk.internal.org.objectweb.asm.Handle;
import lombok.Getter;
import lombok.Setter;
import lombok.experimental.Accessors;/*** <p>* �鱾��Ϣ��* </p>** @author lixiao* @since 2023-12-16*/
@Getter
@Setter
@Accessors(chain = true)
@TableName("t_book")
@ApiModel(value="书本对象")
public class Book implements Serializable {private static final long serialVersionUID = 1L;/*** �鱾���* ASSIGN_ID雪花* ASSIGN_UUID 随机*/@ApiModelProperty(value="书本编号")@TableId(value = "id", type = IdType.ASSIGN_ID)private Long id;/*** �鱾����*/@ApiModelProperty(value="书本名称")@TableField("bookname")private String bookname;/*** �鱾�۸�*/@ApiModelProperty(value="书本价格")@TableField(value = "price",fill = FieldFill.INSERT_UPDATE)private Float price;/*** �鱾����*/@ApiModelProperty(value="书本类型")@TableField(value = "booktype",fill = FieldFill.INSERT_UPDATE)private String booktype;@ApiModelProperty(hidden = true)@TableLogic //逻辑删除private Integer statu;@ApiModelProperty(hidden = true)@Versionprivate Integer version;}

@ApiParam

作用在方法的参数上,用来描述接口的参数信息(一个参设置一个)

@ApiParam必须与@RequestParam@PathVariable@RequestHeader一起使用。

属性说明
name参数名称
value参数简单描述
defaultValue描述参数默认值
required是否为必传参数, false:非必传; true:必传
allowMultiple指定参数是否可以通过多次出现来接收多个值
hidden隐藏参数列表中的参数
example非请求体(body)类型的单个参数示例
examples@Example(value = @ExampleProperty(mediaType = “”, value = “”)) 参数示例,仅适用于请求体类型的请求

案例演示

@ApiOperation(value="新增书本信息1",notes="新增书本信息1")
@PostMapping("/addBooks")
public JsonResponseBody<?> addBooks(@ApiParam(name="bookName",value="bookName",required = true) @RequestParam("bookName") String bookName,@ApiParam(name="price",value="price",required = true) @RequestParam("price") float price,@ApiParam(name="bookType",value="bookType",required = true) @RequestParam("bookType") String bookType){System.out.println("bookName="+bookName+",price="+price+",bookType="+bookType);return new JsonResponseBody<>();
}

5.生产环境下屏蔽Swagger2

打jar包

运行jar

为了保证接口文档的安全,禁用了生产环境的加载,具体说明请看:

一般生产环境是不能放开swagger的,这样接口暴露在外网很不安全!!!

一般生产环境是不能放开swagger的,这样接口暴露在外网很不安全!!!

一般生产环境是不能放开swagger的,这样接口暴露在外网很不安全!!!

5.1.修改Swagger2配置类

添加@Profile注解,指明在何种环境下可以使用Swagger2,一般情况下只有在开发(dev)和测试(test)环境下才可以使用Swagger2;而在生产(dev)环境下不能使用Swagger2。

@Configuration
//开启Swagger2
@EnableSwagger2
//配置生产环境下不可用  dev(开发)、test(测试)、prod(生产)
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport {...
​@Overrideprotected void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");}
}

5.2.修改application.yml

修改application.yml文件,配置项目系统的运行环境(dev/test/prod)

spring:#配置swagger2生产和测试环境不可用profiles:active: prod

5.3.使用maven package打包测试

5.4.运行测试

打开CMD,跳转到target目录,输入命令:java -jar .\xxx.jar --spring.profiles.active=prod。可以直接打开jar包修改application.yml配置文件中spring.profiles.active属性切换运行环境,具体请参考以下配置:

开发环境:dev; 生产环境:prod; 测试环境:test;

      运行命令: java -jar .\yxbook-0.0.1-SNAPSHOT.jar --spring.profiles.active=环境

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

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

相关文章

【蓝桥杯】专题练习

前缀和 3956. 截断数组 - AcWing题库 一看到题目很容易想到的思路是对数组求前缀和&#xff0c;然后枚举两个分段点就好&#xff0c;时间复杂度是On^2&#xff0c;n是1e5会t&#xff0c;需要优化。 朴素的代码&#xff0c;会超时&#xff1a; #include <bits/stdc.h> u…

4-高可用-限流详情

在开发高并发系统时&#xff0c;有很多手段来保护系统&#xff0c;如缓存、降级和限流等。缓存目的是提升系统访问速度和增大系统处理能力&#xff0c;可谓是抗高并发流量的银弹。 而降级是当服务出问题或者影响到核心流程的性能&#xff0c;需要暂时屏蔽掉&#xff0c;待高峰…

亚马逊云科技-如何缩容/减小您的AWS EC2根卷大小-简明教程

一、背景 Amazon EBS提供了块级存储卷以用于 EC2 实例&#xff0c;EBS具备弹性的特点&#xff0c;可以动态的增加容量、更改卷类型以及修改预配置的IOPS值。但是EBS不能动态的减少容量&#xff0c;在实际使用中&#xff0c;用户也许会存在此类场景&#xff1a; 在创建AWS EC2…

【Python】循环语句

一、while循环的基础语法 二、while循环的嵌套应用 三、while循环的嵌套案例 四、for循环的基础语法 五、for循环的嵌套应用 六、循环中断 : break和continue 一、while循环的基础语法 使用while循环的基础应用 while循环语句 while循环注意点 while的条件需得到布尔类型&am…

高并发神经网络推理部署

高并发的神经网络推理框架部署 highport 是一款封装神经网络推理的高并发的软件架构&#xff0c;已在ESWEEK 2023年皮肤病检测比赛中获得第一名。 这里记录一下highport的软件架构和几个trick优化 软件架构图 解密模块&#xff1a;我们训练完的模型文件是带加密的&#xff0c;…

2023优秀开源项目获选榜名单(开放原子开源基金会)|JeecgBoot 成功入选

JeecgBoot 是一个开源的企业级低代码开发平台&#xff0c;它成功入选2023年度生态开源项目&#xff0c;这是对其十年坚持开源的认可。作为一个开源项目&#xff0c;JeecgBoot 在过去的十年里一直秉承着开放、共享、协作的理念&#xff0c;不断推动着开源社区的发展。 2023年开放…

在windows上如何干净的卸载一个软件及其快捷方式

可以在控制面板里面卸载&#xff0c;可以卸载掉文件夹及其快捷方式&#xff0c;具体操作如下&#xff1a; 找到-》控制面板\程序\程序和功能 然后右键某一项&#xff0c;即可出现卸载功能项。 卸载不干净的方法&#xff1a;利用软件商店卸载&#xff0c;有可能卸载失败&#x…

maven学习和maven聚合工程搭建

1.学习maven maven的概念 项目管理工具 &#xff0c;对jar进行依赖管理&#xff0c;编译&#xff0c;打包&#xff0c;单元测试&#xff0c;安装&#xff0c;部署&#xff0c;贯穿整个项目 为什么要学maven 要解决的问题&#xff1a; 不同的开发工具开发出来的项目目录结构…

网络通信day5作业

1> 使用select完成TCP客户端程序 客户端: #include<myhead.h>#define FPORT 9999 #define FIP "192.168.125.130"#define KPORT 6666 #define KIP "192.168.125.130"int main(int argc, const char *argv[]) {//创建套接字文件描述符int cfd…

Android: Ubuntu下交叉环境编译常用调试工具demo for lspci命令(ARM设备)

lspci命令交叉环境编译(ARM设备) 交叉编译工具下载&#xff1a; https://releases.linaro.org/components/toolchain/binaries https://releases.linaro.org/components/toolchain/binaries/6.3-2017.05/aarch64-linux-gnu/ lspci命令交叉环境编译(ARM设备)&#xff1a; 1&a…

智能优化算法应用:基于梯度算法3D无线传感器网络(WSN)覆盖优化 - 附代码

智能优化算法应用&#xff1a;基于梯度算法3D无线传感器网络(WSN)覆盖优化 - 附代码 文章目录 智能优化算法应用&#xff1a;基于梯度算法3D无线传感器网络(WSN)覆盖优化 - 附代码1.无线传感网络节点模型2.覆盖数学模型及分析3.梯度算法4.实验参数设定5.算法结果6.参考文献7.MA…

IDEA中如何创建各种类型的java工程

如果你的工程下面的module没有互相依赖&#xff0c;就相当于是一个小的项目&#xff0c;idea版本不同&#xff0c;细节可能不同 1、普通的Java 工程 在工程上&#xff0c;右键- New - Module&#xff0c;如下&#xff1a; 指明Java工程的名称及使用的JDK版本&#xff1a; 创建…

基于扩散的模糊文本图像超分辨率技术

恢复低分辨率文本图像具有挑战性&#xff0c;特别是对于在现实场景中具有复杂笔画和严重降质的中文文本图像。确保文本的准确性和样式的真实性对于高质量的文本图像超分辨率至关重要。最近&#xff0c;由于扩散模型强大的数据分布建模能力和数据生成能力&#xff0c;在自然图像…

Python---IP 地址的介绍

1. IP 地址的概念 IP 地址就是标识网络中设备的一个地址&#xff0c;好比现实生活中的家庭地址。 网络中的设备效果图: 2. IP 地址的表现形式 说明: IP 地址分为两类&#xff1a; IPv4 和 IPv6 IPv4 是目前使用的ip地址 IPv6 是未来使用的ip地址 IPv4 是由点分十进制组成 …

Pycharm 关闭控制台多余窗口详解(console)

文章目录 1 问题描述2 解决办法2.1 步骤1&#xff1a;编辑配置2.2 步骤2&#xff1a;使用 Python 控制台运行&#xff08;取消勾选&#xff09;2.3 验证&#xff1a;再次运行&#xff0c;多余窗口消失 1 问题描述 2 解决办法 2.1 步骤1&#xff1a;编辑配置 菜单路径&#xf…

anconda常用命令

一、基础指令说明 1、查看anconda版本号 conda --version 2、查看当前已有虚拟环境 conda env list 3、创建新环境 conda create -n classify python3.9 创建一个叫做classify的虚拟环境&#xff0c;其中python等于3.9 4、进入虚拟环境 activate classify 5、安装包 接下来…

5213A 综合数据通信分析仪

5213A 综合数据通信分析仪 数字通信测量仪器 5213A 综合数据通信分析仪是符合标准 PXI/CPCI 总线的模块化便携式仪器&#xff0c;用户可以 根据测试需要选配相应的模块&#xff0c;可选模块包括双端口 RapidIO 模块、双端口 2G FC 模块、双 端口 4G FC 模块、双端口 8G FC 模…

HP服务器idrac设置以及系统安装

HP服务器idrac设置以及系统安装 一、设置管理口的地址和密码1、HP服务器重新界面选择"F9"进入BIOS&#xff0c;设置iLo5(idrac)的IP和用户名密码。2、选择"系统配置"。3、选择"iLO 4"配置程序。4、网络选项是设置idrac管理口的地址&#xff0c;设…

grafana基本使用

一、安装grafana 1.下载 官网下载地址&#xff1a; https://grafana.com/grafana/download官网包的下载地址&#xff1a; yum install -y https://dl.grafana.com/enterprise/release/grafana-enterprise-10.2.2-1.x86_64.rpm官网下载速度非常慢&#xff0c;这里选择清华大…

Linux 操作系统(Vim)

vim 编译器&#xff08;相当于windows中记事本&#xff09; 当在终端窗口直接运行vim命令&#xff0c;会出现以下截图&#xff08;类似手册对vim编译器简单的介绍&#xff09;&#xff1a; vim提供三种基本工作模式&#xff1a; 命令模式(默认模式) 插入模式 末行模式 创建文本…