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.rhkb.cn/news/266762.html

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

相关文章

Huggingface初上手即ERNIE-gram句子相似性实战

大模型如火如荼的今天&#xff0c;不学点语言模型&#xff08;LM&#xff09;相关的技术实在是说不过去了。只不过由于过往项目用到LM较少&#xff0c;所以学习也主要停留在直面——动眼不动手的水平。Huggingface&#xff08;HF&#xff09;也是现在搞LM离不开的工具了。 出于…

k8s pv与pvc理解与实践

参考文章&#xff1a; https://blog.csdn.net/qq_41337034/article/details/117220475 一、 pv/pvc简述 Pv是指PersistentVolume&#xff0c;中文含义是持久化存储卷是对底层的共享存储的一种抽象&#xff0c;Pv由管理员进行配置和创建&#xff0c;只要包含存储能力&#xff…

Rocky Linux 安装部署 Zabbix 6.4

一、Zabbix的简介 Zabbix是一种开源的企业级监控解决方案&#xff0c;用于实时监测服务器、网络设备和应用程序的性能和可用性。它提供了强大的数据收集、处理和可视化功能&#xff0c;同时支持事件触发、报警通知和自动化任务等功能。Zabbix易于安装和配置&#xff0c;支持跨平…

论文阅读:2020GhostNet华为轻量化网络

创新&#xff1a;&#xff08;1&#xff09;对卷积进行改进&#xff08;2&#xff09;加残差连接 1、Ghost Module 1、利用1x1卷积获得输入特征的必要特征浓缩。利用1x1卷积对我们输入进来的特征图进行跨通道的特征提取&#xff0c;进行通道的压缩&#xff0c;获得一个特征浓…

C语言第三十三弹---动态内存管理(上)

✨个人主页&#xff1a; 熬夜学编程的小林 &#x1f497;系列专栏&#xff1a; 【C语言详解】 【数据结构详解】 动态内存管理 1、为什么要有动态内存分配 2、malloc和free 2.1、malloc 2.2、free 3、calloc和realloc 3.1、calloc 3.2、realloc 4、常见的动态内存的错…

阿里云短信验证笔记

1.了解阿里云的权限操作 进入AccessKey管理 选择子用户 创建用户组和用户 先创建用户组&#xff0c;建好再进行权限分配 添加短信管理权限 创建用户 创建好后的id和密码在此处下载可以得到 2.开通阿里云短信服务 进行申请&#xff0c;配置短信模板 阿里云短信API文档 短信服务…

MySQL 逗号分隔查询--find_in_set()函数

业务场景&#xff1a; 在使用MySQL的时候&#xff0c;可能的某个字段存储的是一个英文逗号分割的字符串&#xff08;这里我们不讨论表设计的合理性&#xff09;&#xff0c;如图所示&#xff1a; 我们在查询的时候需要匹配逗号分割中的某个字符串&#xff0c;该怎么查询呢&am…

地图可视化绘制 | R-ggplot2 NC地图文件可视化

在推出两期数据分享之后&#xff0c;获取数据的小伙伴们也知道&#xff0c;数据格式都是NetCDF(nc) 格式网格数据&#xff0c;虽然我在推文分享中说明使用Python、R或者GIS类软件都是可以进行 处理和可视化绘制的&#xff0c;但是&#xff0c;还是有小伙伴咨询使用编程软件Pyth…

浅谈mysql mvcc

目录 前言 mvcc 是如何工作的&#xff1f; 数据的更新 前言 mvcc 与一个事物的隔离级别有关&#xff0c;未提交读永远读的是当前值&#xff0c;串行化是通过加锁实现&#xff0c;这两种隔离级别都与mvcc 没有任何关系。只要一提到mvcc应该想到的是读提交以及可重复读&#…

Spring八股 常见面试题

什么是Spring Bean 简单来说&#xff0c;Bean 代指的就是那些被 IoC 容器所管理的对象。我们需要告诉 IoC 容器帮助我们管理哪些对象&#xff0c;这个是通过配置元数据来定义的。配置元数据可以是 XML 文件、注解或者 Java 配置类。 将一个类声明为 Bean 的注解有哪些? Com…

【buuctf-gakki】

binwalk 查看图片&#xff0c;发现有 rar 文件&#xff0c;提取后如上图所示&#xff08;flag.txt为已经解压后出来的&#xff09;其中这个 rar 需要用 archpr爆破一下 打开后一个 flag.txt 一堆杂乱无章的字符&#xff0c;需要用到 python 脚本进行词频统计&#xff0c;我们…

Vue3 在SCSS中使用v-bind

template 先创建一个通用的页面结构 <template><div class"v-bubble-bg"></div> </template>js 在JS中先对需要用的数据进行定义&#xff1a; 可以是参数&#xff0c;也可以是data <script setup>const props defineProps({bgCol…

设计模式系列文章-7个创建型模式更新已完结

其实从2019年开始就有些一套关于设计模式的系列文章&#xff0c;但是因为种种原因一直搁置到现在。直到2024年才又恢复更新。 24年1月份上旬一直在弄博客站&#xff1a;https://jaune162.blog 的搭建 24年1月份下旬弄专题站&#xff1a;https://books.jaune162.blog 的搭建。…

本地写的Bash脚本,Linux端运行报错:/bin/bash^M: bad interpreter: No such file or directory

背景 在本地写了个Bash Shell脚本&#xff0c;但上传到Linux端后加完权限执行时报错&#xff1a; &#xff08;脚本名&#xff1a;script.sh&#xff09; -bash: ./script.sh: /bin/bash^M: bad interpreter: No such file or directory 分析 这个错误通常是由于脚本文件的行…

beets,一个有趣的 Python 音乐信息管理工具!

前些天发现了一个巨牛的人工智能学习网站&#xff0c;通俗易懂&#xff0c;风趣幽默&#xff0c;忍不住分享一下给大家。点击跳转到网站AI学习网站。 目录 前言 什么是Beet库&#xff1f; 安装Beet库 使用Beet库 Beet库的功能特性 1. 多种音乐格式支持 2. 自动标签识…

LNMP架构介绍及配置--部署Discuz社区论坛与wordpress博客

一、LNMP架构定义 1、LNMP定义 LNMP&#xff08;Linux Nginx Mysql Php&#xff09;是指一组通常一起使用来运行动态网站或者服务器的自由软件名称首字母缩写&#xff1b;Linux系统下NginxMySQLPHP这种网站服务器架构。 Linux是一类Unix计算机操作系统的统称&#xff0c;是目…

力扣2月最后三天的每日一题

力扣2月最后三天的每日一题 前言2867.统计树中的合法路径数目思路确定1e5中的质数统计每个点的连接情况开始对质数点进行处理完整代码 2673.使二叉树所有路径值相等的最小代价思路完整代码 2581.统计可能的树根数目思路建立连通关系将猜测数组变为哈希表&#xff0c;方便查询利…

利用 Python 抓取数据探索汽车市场趋势

一、引言 随着全球对环境保护意识的增强和技术的进步&#xff0c;新能源汽车作为一种环保、高效的交通工具&#xff0c;正逐渐受到人们的关注和青睐。在这个背景下&#xff0c;对汽车市场的数据进行分析和研究显得尤为重要。 本文将介绍如何利用 Python 编程语言&#xff0c;结…

STM32标准库——(14)I2C通信协议、MPU6050简介

1.I2C通信 I2C 通讯协议(Inter&#xff0d;Integrated Circuit)是由Phiilps公司开发的&#xff0c;由于它引脚少&#xff0c;硬件实现简单&#xff0c;可扩展性强&#xff0c; 不需要USART、CAN等通讯协议的外部收发设备&#xff0c;现在被广泛地使用在系统内多个集成电路(IC)间…

BCN-活性酯,BCN-活性酯,可用于合成双环壬酮功能化聚乙二醇聚合物涂层

您好&#xff0c;欢迎来到新研之家 文章关键词&#xff1a;1516551-46-4&#xff0c;BCN-NHS&#xff0c; BCN-NHS 酯&#xff0c;BCN-活性酯&#xff0c;BCN-succinimidylester&#xff0c;丙烷环辛炔-活性酯&#xff0c;BCN-琥珀酰亚胺酯 一、基本信息 【产品简介】&#…