Swagger3 使用详解

Swagger3 使用详解

  • 一、简介
    • 1 引入依赖
    • 2 开启注解
    • 3 增加一个测试接口
    • 4 启动服务报错
    • 1.5 重新启动
    • 6 打开地址:http://localhost:8093/swagger-ui/index.html
  • 二、Swagger的注解
    • 1.注解@Api和@ApiOperation
    • 2.注解@ApiModel和@ApiModelProperty
    • 3.注解@ApiImplicitParams和@ApiImplicitParam
    • 4.注解@ApiResponses和ApiResponse
    • 5.注解@ApiIgnore
  • 三、Swagger的相关配置

一、简介

官方网站:https://swagger.io/
Swagger 是一个开源的 API 开发和文档框架,Swagger 旨在简化 RESTful API 的设计、开发、测试、文档化和消费过程。Swagger的出现节约了大量的后端人员对接接口的时间,通过Swagger可以快速定义接口文档,方便了前端后端的接口对接工作,废话不多说直接上用例。
这里使用的SpringBoot 是2.6.11 版本

1 引入依赖

<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version>
</dependency>

2 开启注解

启动类增加注解

@EnableSwagger2
// 或者使用下面的注解,也是可以的
@EnableOpenApi

3 增加一个测试接口

增加一个接口,方便看到Swagger帮我们生成的接口文档中的接口信息,如下:

package com.cheng.ebbing.message.controller;import com.cheng.ebbing.message.vo.UserVO;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;/*** @author pcc* @version 1.0.0* @description 测试接口*/
@RestController
public class TestController {@RequestMapping(value ="/test")public UserVO test(){return new UserVO("zhangsan","1234",1);}
}

4 启动服务报错

报错:Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException
原因可以参考这篇文章 https://blog.csdn.net/weixin_45131680/article/details/131580270,总结一句话就是SpringBoot2.6以上的版本整合Swagger2:3.0.0会碰到这个问题,根本原因是路径匹配模式不适配。解决方案有两个,他们的目的是为了更改路径匹配规则以适配Swagger2 的3.0 的版本。

  • 解决方案一:
    // 启动类增加了开启swagger注解的基础上增加以下注解
    @EnableWebMvc
    
  • 解决方案二:
    配置文件增加以下配置:
    spring:mvc:pathmatch:matching-strategy: ant_path_matcher
    

1.5 重新启动

选择上面其中一个方案进行解决即可,然后重新启动就会正常了,如下:
在这里插入图片描述

6 打开地址:http://localhost:8093/swagger-ui/index.html

到这里swagger的入门集成就成功了,如果你没有设置项目的根路径,那么Swagger的地址就是这个了,如果设置了自行端口后增加根路径就行,打开后如下图:
在这里插入图片描述
界面里有四块信息是需要关注的。
左一:展示的信息支持自定义,可以用来标识文档的和服务的信息(第四部分进行详细介绍)
左二:接口展示,这里展示接口的详细信息,最常用的地方,可以看到上面定义的测试接口已经在这里了(第二部分详细介绍)
左三:这里展示我们再请求和响应中定义的实体信息,比如上面接口的UserVO就在这里(第二部分详细介绍)
右一:分组信息,一般用于多个微服务时对不同微服务进行分组,常用与和Gateway集成时对服务进行分组展示(第三部分详细介绍)

二、Swagger的注解

这里详细说下Swagger常用的注解,根据使用频率来进行先后说明。这里分为了五个部分来说,前四个部分都是分组来说的,每组注解基本都是一起使用的所以就放一起来说,也方便理解记忆。下面的前四组例子都将使用使用注解和不使用注解的方式来进行说明比对,以此来方便了解注解的具体的作用。

1.注解@Api和@ApiOperation

这是使用频率最高的一组注解了。@Api常用与接口类上,用以对当前的接口类做整体声明。@ApiOperation则用于接口方法上,用以描述具体的方法真。

  • @Api
    正使用时其实只需要为@Api声明tags标签即可(其他的基本用不到,如果需要再阅读下注解的源码即可),value的值在源码描述中说是当tags不使用时会将其作为资源的描述,但是笔者试了没啥用,而且大家都是使用tags,直接使用tags标签即可。假如存在下面两个方法,他们的信息基本都是相同的,一个使用了@Api注解,一个没有使用:

    // 使用了 @Api注解的类
    @Api(tags = "测试接口类1")
    @RestController
    public class TestController1 {@PostMapping("/test1Fun")public String test() {return "test1";}
    }// 未使用@Api注解的类
    @RestController
    public class TestController2 {@PostMapping("/test2Fun")public String test() {return "test2";}
    }
    

    下面一起看下他们在Swagger中的展示区别吧(注意重启生效):
    在这里插入图片描述
    可以看到使用后多了汉字的描述,这样对于文档使用者来说也就更为有好了,这也就是tags属性的作用了,其他属性基本不咋使用。

  • @ApiOperation
    这个注解则是使用在接口方法上的,用以描述一个具体的接口,它支持的所有属性都是和RequestMapping对应的,因为他本来就是用来描述接口的和RequestMapping对应则是很好理解的。不过最常用的还是他的value属性,用以简介当前的接口。其他用以描述接口的信息一般不设置也是可以看到的,我们一般使用value属性简单描述接口的作用。
    下面是一组使用@ApiOperation和不使用的代码:

    
    // 使用注解@ApiOperation
    @ApiOperation("测试接口1-方法1")
    @PostMapping("/test1Fun")
    public String test() {return "test1";
    }// 不使用注解@ApiOperation
    @PostMapping("/test2Fun")
    public String test() {return "test2";
    }
    

    下面一起看下使用注解和不使用注解在Swagger中的区别:
    在这里插入图片描述

2.注解@ApiModel和@ApiModelProperty

这组注解是使用在实体上的,一般前后端参数交互时都是使用Json数据进行交互,Json交互时后端使用实体和注解@RequestBody来接收前端传递的参数,而这组注解则是用来描述实体的。实体既可以作为接收参数当然也可以作为返回参数。下面一起来看下。

  • @ApiModel
    被用于修饰实体类,实体类可用于接口入参和返参,一般只使用value属性即可。假设有如下两个实体信息,一个加了ApiModel一个没有加:

    // 使用了注解@ApiModel的注解
    @Data
    @ApiModel("用户实体1")
    @AllArgsConstructor
    @NoArgsConstructor
    public class UserVO1 implements Serializable {private static final long serialVersionUID = 1L;private String username;private String password;Integer id;
    }// 不使用注解@ApiModel
    @Data
    @AllArgsConstructor
    @NoArgsConstructor
    public class UserVO2 implements Serializable {private static final long serialVersionUID = 1L;private String username;private String password;Integer id;
    }
    

    先看下使用了注解时的样子(不使用则显示类名):
    在这里插入图片描述
    下面是不使用的样子:
    在这里插入图片描述
    此外在下面的位置也是可以看出区别的:
    在这里插入图片描述

  • @ApiModelProperty
    这个属性被用在实体的属性上,用来标识实体属性的含义,这个还是很有用的,因为不用他来标识的话有些字段是人无法知道具体代表的含义的。这个也是基本使用value即可,下面也是使用使用和不使用注解来比对下区别,这里就只贴使用注解的代码了

    @Data
    @ApiModel("用户实体1")
    @AllArgsConstructor
    @NoArgsConstructor
    public class UserVO1 implements Serializable {private static final long serialVersionUID = 1L;@ApiModelProperty("用户名")private String username;@ApiModelProperty("用户密码")private String password;@ApiModelProperty("用户ID")Integer id;
    }
    

    下面是在swagger文章中看到的区别:
    在这里插入图片描述

3.注解@ApiImplicitParams和@ApiImplicitParam

上面一组注解被用于标识使用实体接收和返回的数据对象,那么如果接受的数据不是json呢,则需要别的注解来处理了,这一组注解就可以实现这个功能。

  • 参数传递大致有以下几种
    • 1.使用body传递json,后端使用注解RequestBody来接收
    • 2.使用body传递form-data,后端使用注解RequestParam接收(文件除外)
    • 3.使用body传递x-www-form-urlencoded,后端使用注解RequestParam接收
    • 4.使用path传参(restful),后端使用注解PathVariable来接收
    • 5.使用query传参,即url传参,后端使用注解RequestParam接收
    • 6.使用Cookie传参,后端使用注解CookieValue接收

上面列举了集中数据的传递方式,可以看到除了Json进行传递,还有一些其他的数据传递,此时@ApiModel这组注解就无法满足我们的需要了,那就只能使用@ApiImplicitParams和@ApiImplicitParam。上面的这些数据传递(除了json)都会在接口方法有参数进行映射。所以使用这组注解就都可以进行声明。这组注解和上面还有一点区别就是必须同时使用。

这里使用query传参进行说明吧。假设有如下接口代码:

@ApiOperation("测试接口1-方法1")
@PostMapping("/test1Fun")
public UserVO1 test(@RequestParam("name")String name) {return new UserVO1("用户1","1234",10);
}

不使用注解时,swagger展示如下:
在这里插入图片描述
当添加了如下注解以后:

@ApiOperation("测试接口1-方法1")
@PostMapping("/test1Fun")
@ApiImplicitParams({@ApiImplicitParam(name = "name",value = "用户名",required = true,paramType = "query",dataType = "String",dataTypeClass = String.class)
})
public UserVO1 test(@RequestParam("name")String name) {return new UserVO1("用户1","1234",10);
}

swagger中展示如下:
在这里插入图片描述
注意:可以看到只是多了在注解ApiImplicitParam中描述的value其他都是相同的,所以说其实使用这组注解时只需要关注ApiImplicitParam他的value就行了。不过需要注意的是这里还是用了注解@RequestParam,swagger文档中的required和query是这个注解赋予的,如果没有这个注解swagger文档是不会有对应提示的。还有一点,若是使用ApiImplicitParam的dataType则一定要使用dataTypeClass不然会一直提示warn日志
在这里插入图片描述

4.注解@ApiResponses和ApiResponse

上一组注解时用来描述除了实体以外的入参的,这个注解从字面看就知道是跟返回信息有关的,先看下不加这个注解时的接口的返回在swagger中的展示:
在这里插入图片描述
然后我们为接口增加这组注解,如下:

    @ApiOperation("测试接口1-方法1")@PostMapping("/test1Fun")@ApiResponses({@ApiResponse(code = 200, message = "成功", response = UserVO1.class,reference = "UserVO1"),@ApiResponse(code = 400, message = "失败",response = UserVO1.class,reference = "UserVO1")})public UserVO1 test(@RequestParam("name")String name) {return new UserVO1("用户1","1234",10);}

下面是使用注解后的swagger文档展示:
在这里插入图片描述
可以看到真正有作用的是code和message,所以如果需要使用就使用这两个即可,不过一把不使用这组注解,因为后端服务一般不会抛出http的异常码,而是通过实体的错误码来标识响应信息。

5.注解@ApiIgnore

这个注解也比较简单,可以使用在类或者方法上都是可以的,用以将其排除,排除后swagger不会将其加入文档。
假如有如下代码:

    @ApiIgnore@ApiOperation("测试接口1-方法1")@PostMapping("/test1Fun")@ApiResponses({@ApiResponse(code = 200, message = "成功", response = UserVO1.class,reference = "UserVO1"),@ApiResponse(code = 400, message = "失败",response = UserVO1.class,reference = "UserVO1")})public UserVO1 test(@RequestParam("name")String name) {return new UserVO1("用户1","1234",10);}

因为加了该注解,我们再swagger中是看不到的:
在这里插入图片描述

三、Swagger的相关配置

其实不添加任何配置不影响使用,但知道配置方便我们更好地针对自己的特别需求进行定制化。所以配置还是需要进行了解和熟悉的。比如生产上是不推荐打开swagger的,因为有很大的安全隐患。下面一起说下,注意这些配置信息都需要放在配置文件,这里为了方便都直接写死了。

package com.cheng.ebbing.message;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;/*** @author pcc* @version 1.0.0* @description swagger3配置类*/
@EnableWebMvc // 适配springboot2.6和swagger3
@EnableOpenApi // 开启swagger3
@Configuration
public class config {@Beanpublic Docket  createRestApi(){return new Docket(DocumentationType.OAS_30).enable(true) // 开启swagger,生产建议关闭.apiInfo(apiInfo()) // 配置文档的基础信息.groupName("这是分组名")// 不设置默认都是default,单个服务可以不使用分组,如果想要多个分组再来个Docket设置组名即可.select() // 开始配置路径相关信息// 扫描固定包,其他包下的信息不回出现在swagger.apis(RequestHandlerSelectors.basePackage("com.cheng.ebbing"))// 扫描所有有注解的api,用这种方式更灵活,也可以扫描指定的接口,支持通配符.paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {// 配置文档的基础信息,例如标题、描述等return new ApiInfoBuilder().title("这是title").description("这是description").license("这是license").licenseUrl("这是licenseUrl").termsOfServiceUrl("这是termsOfServiceUrl").contact(new Contact("concat-name","concat-url","concat-email")).version("版本1.0.0").build();}
}

增加完配置信息以后,swagger文档展示如下:
在这里插入图片描述
这些配置信息,注意不要直接写死,而应该从配置文件获取,这里直接写死只是为了演示使用,swagger只是项目辅助的小框架就只说到这里了。

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

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

相关文章

大数据职业技术培训包含哪些

技能提升认证考试&#xff0c;旨在通过优化整合涵盖学历教育、职业资格、技术水平和高新技术培训等各种教育培训资源&#xff0c;通过大数据行业政府引导&#xff0c;推进教育培训的社会化&#xff0c;开辟教育培训新途径&#xff0c;围绕大数据技术人才创新能力建设&#xff0…

【华为面试基础题】求字符串中所有整数的最小和

描述 字符串s&#xff0c;只包含 a-z A-Z - &#xff1b; 合法的整数包括 1&#xff09; 正整数 一个或者多个0-9组成&#xff0c;如 0 2 3 002 102 2&#xff09;负整数 负号 - 开头&#xff0c;数字部分由一个或者多个0-9组成&#xff0c;如 -0 -012 -23 -00023 输入描述&…

targetSdkVersion > 30 如何将下载的网络视频 保存到手机相册里更新

在 targetSdkVersion 31 中&#xff0c;将下载的网络视频保存到手机相册中涉及几个关键步骤。由于 Android 12&#xff08;API 级别 31&#xff09;引入了更多的隐私和安全限制&#xff0c;特别是作用域存储&#xff08;Scoped Storage&#xff09;&#xff0c;因此你需要遵循这…

java特殊文件、日志技术、多线程

一、属性文件 1.1 特殊文件概述 像这种普通的文本文件&#xff0c;没有任何规律可言&#xff0c;不方便程序对文件中的数据信息处理。 在以后的Java开发过程中还会遇到一些特殊的文本文件&#xff0c;这些文件是有一些格式要求的&#xff0c;方便程序对文件中的数据进行处理。…

机器学习-02-机器学习算法分类以及在各行各业的应用

总结 本系列是机器学习课程的第02篇&#xff0c;主要介绍机器学习算法分类以及在各行各业的应用 本门课程的目标 完成一个特定行业的算法应用全过程&#xff1a; 定义问题&#xff08;Problem Definition&#xff09; -> 数据收集(Data Collection) -> 数据分割(Data…

自然语言处理: 第十三章Xinference部署

项目地址: Xorbitsai/inference 理论基础 正如同Xorbits Inference&#xff08;Xinference&#xff09;官网介绍是一个性能强大且功能全面的分布式推理框架。可用于大语言模型&#xff08;LLM&#xff09;&#xff0c;语音识别模型&#xff0c;多模态模型等各种模型的推理。通…

Spring中 Unsupported class file major version 61 报错

初学Spring时遇到的一个错误&#xff1a;Unsupported class file major version 61 &#xff0c;如图所示&#xff1a; 网上查了一下大概是JDK的版本与Spring的版本不一致导致的错误&#xff1b;刚开始我用的Spring版本是&#xff1a; <dependencies><dependency>…

StarRocks实战——多维分析场景与落地实践

目录 一、OLAP 系统历史背景 1.1 历史背景与痛点 1.2 组件诉求 二、StarRocks 的特点和优势 2.1 极致的查询性能 2.2 丰富的导入方式 2.3 StarRocks 的优势特点 三、多维分析的运用场景 3.1 实时计算场景 / 家长监控中心 3.2 实时更新模型选择 3.2.1 更新模型UNIQU…

Eureka简介与使用浅析

Eureka 简介 Eureka 是 Netflix 开发的一款开源服务发现组件&#xff0c;主要用于构建云环境下的微服务架构。它是基于 REST (Representational State Transfer) 的服务&#xff0c;扮演了服务注册与发现的角色&#xff0c;在分布式系统中尤为重要。Eureka Server 作为一个中心…

JDK, JRE, 和 JVM 的解释

在Java编程中&#xff0c;JDK&#xff08;Java Development Kit&#xff0c;Java开发工具包&#xff09;、JRE&#xff08;Java Runtime Environment&#xff0c;Java运行环境&#xff09;和JVM&#xff08;Java Virtual Machine&#xff0c;Java虚拟机&#xff09;是三个核心概…

正则表达式常见的应用场景

数据格式验证&#xff1a;正则表达式可以用来验证输入数据的格式是否符合要求。例如&#xff0c;可以使用正则表达式验证一个邮箱地址是否符合邮箱的格式规范&#xff0c;或者验证一个手机号码是否符合手机号码的格式规范。这在开发网站、手机应用程序等需要用户输入数据的场景…

考研数据结构算法机试训练1

中南大学上机压轴题 测试数据&#xff1a; 3 500 0.6 100 0.8 200 0.7 100 输出 390首先要对输入的折扣进行排序&#xff0c;优先使用比率低的z进行支付。 然后用lowcost记录目前多少钱是打过折的。T-lowcost就是剩余没打折的。 每次循环用上一个人的折扣额度。若所有人折扣额…

2402C++,C++使用单链列表

原文 #include <windows.h> #include <malloc.h> #include <stdio.h>//用于列表项的结构;第一个成员是SLIST_ENTRY结构,其他成员是数据.在此,数据只是测试 typedef struct _PROGRAM_ITEM {SLIST_ENTRY ItemEntry;ULONG Signature; } PROGRAM_ITEM, *PPROGR…

nodejs 实现pdf与图片互转

PDF转图片 效果图 代码 const path require(path); const pdf require(pdf-poppler); const fs require(fs); // PDF文件路径 const pdfFilePath ./path/test.pdf; // 转换选项 const opts { format: png, // 输出图片格式&#xff0c;可以是 jpeg, png, ppm…

3d 舞蹈同步

目录 看起来很强大 unity驱动bvh跳舞&#xff1a; 脚飘动问题&#xff1a; bvh和播放关节对应关系 zxy格式 bvh和播放关节对应关系 zyx的对应关系&#xff1a; bvh播放器&#xff1a; 看起来很强大 GitHub - FORTH-ModelBasedTracker/MocapNET: We present MocapNET, a …

AIGC(生成式人工智能)如何掀起数字化转型的巨浪?

数字化转型已成为当下企业发展的必经之路&#xff0c;而生成式AI作为这场变革的强力引擎&#xff0c;正逐渐展现出其无与伦比的价值。今天&#xff0c;我们将深入探讨生成式AI在日志整理、数据清晰、产品设计等方面的应用&#xff0c;揭示它如何为数字化转型注入强大动力&#…

centos7 无网络安装telnet

一、上传压缩包telnet-20240227.zip并解压 unzip -o telnet-20240227.zip 二、依次安装rpm包 rpm -ivh xinetd-2.3.15.el7.x86_64.rpm rpm -ivh telnet-0.17-65.el7.x86_64.rpm rpm -ivh telnet-server-0.17-65.el7.x86_64.rpm 三、查看是否安装成功 rpm -qa | grep telnet…

数据结构-关键路径

介绍 在AOV网的基础上&#xff0c;如果用对应边来表示活动持续时间&#xff0c;这种有向图被称为AOE网在AOE网中&#xff0c;入度为0的为源点&#xff0c;出度为0的为汇点&#xff0c;整张网看做是一件事情完成的过程&#xff0c;那么这两个点就是事情的开始和结束。每个活动持…

WPF的DataGrid自动生成中文列头

直接将一个对象集合绑定到DataGrid上面&#xff0c;设置自动生成列AutoGenerateColumns"True"&#xff0c;DataGrid会自动根据对象类的属性生成对应的列 示例类对象&#xff1a; public class DataModel{public int Id { get; set; }public string Name { get; set;…

Rocky Linux 运维工具yum

一、yum的简介 ​​yum​是用于在基于RPM包管理系统的包管理工具。用户可以通过 ​yum​来搜索、安装、更新和删除软件包&#xff0c;自动处理依赖关系&#xff0c;方便快捷地管理系统上的软件。 二、yum的参数说明 1、install 用于在系统的上安装一个或多个软件包 2、seach 用…