手把手教会如何掌握Swagger

文章目录

  • 前言
  • 一、Swagger重要组件及作用
  • 二、SpringBoot集成Swagger
    • 1.环境准备
    • 2.配置Swagger
    • 3.配置Swagger扫描接口
    • 4.配置API分组
    • 5.拓展:其他皮肤
  • 三、常用注解
    • 1.接口注解
    • 2.方法及参数注解
    • 3.实体类注解
    • 效果如图: ![在这里插入图片描述](https://img-blog.csdnimg.cn/4b129cc61659480281187fe471191f18.png)
  • 总结


前言

Swagger是一个用于设计、构建、文档化和消费RESTful Web服务的开源工具集。它的主要目标是简化API的开发和维护,同时提供自动生成的交互式API文档。


一、Swagger重要组件及作用

1.SWAGGER官网主要提供了几种开源工具:

  • Swagger Codegen: 通过Codegen可以将描述文件生成html格式和cwiki形式的接口文档,同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包,docker,node等方式在本地化执行生成。也可以在后面的SwaggerEditor中在线生成。
  • Swagger UI:提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。
  • Swagger Editor:类似于markendown编辑器的编辑Swagger描述文件的编辑器,该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
  • Swagger Inspector: 和postman差不多,是一个可以对接口进行测试的在线版的postman。比在SwaggerUI里面做接口请求,会返回更多的信息,也会保存你请求的实际请求参数等数据。
  • Swagger Hub:集成了上面所有项目的各个功能,你可以以项目和版本为单位,将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作,需要注册账号,分免费版和收费版。
  • Springfox Swagger: Spring 基于swagger规范,可以将基于SpringMVC和Spring Boot项目的项目代码,自动生成JSON格式的描述文件。本身不是属于Swagger官网提供的,在这里列出来做个说明,方便后面作一个使用的展开。其实swagger是有两个版本的,区别还挺大的,一个是swagger-ui也就是swagger1;还有一个是springfox-swagger也就是swagger2;

2.Swagger的优点:

  • 自动文档生成: Swagger可以自动生成API文档,减少了手动编写文档的工作量,并保持文档与实际API的同步。
  • 易于使用: Swagger提供了直观的界面,使开发人员能够轻松了解和测试API。
  • 提高开发效率: 自动生成的客户端和服务器端代码可以节省开发时间,减少了潜在的错误。
  • 标准化: Swagger采用标准的OpenAPI规范,有助于在不同的开发团队和工具之间实现互操作性。
  • 支持多种编程语言: Swagger支持多种编程语言和框架,使其适用于各种技术栈的项目。

二、SpringBoot集成Swagger

1.环境准备

1.1添加Maven依赖

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

1.2.编写HelloController,测试确保运行成功

@RestController
public class HelloController {@RequestMapping("/hello")public String hello(){return "hello";}
}

1.3.编写一个配置类-SwaggerConfig来配置 Swagger

@Configuration
@EnableSwagger2//开启Swagger2的自动配置
public class SwaggerConfig {
}

1.4.访问测试 :http://localhost:8080/swagger-ui.html ,可以看到swagger的界面;

在这里插入图片描述
如果启动报错空指针是因为springboot2.6.0中将SpringMVC 默认路径匹配策略从AntPathMatcher 更改为PathPatternParser,导致出错可以在启动类上加上@EnableWebMvc注解或者在配置中切换为原先的AntPathMatcher:

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

2.配置Swagger

2.1Swagger实例Bean是Docket,所以通过配置Docket实例来配置Swagger

@Bean //配置docket以配置Swagger具体参数
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2);
}

2.2.通过apiInfo()属性配置文档信息

//配置文档信息
private ApiInfo apiInfo() {Contact contact = new Contact("杨树林", "http://yangshulin.com/联系人访问链接", "yangshulin_emila@163.com");return new ApiInfo("Swagger学习", // 标题"学习演示如何配置Swagger", // 描述"v1.0", // 版本"http://apesource.com", // 组织链接contact, // 联系人信息"Apach 2.0 许可", // 许可"许可链接", // 许可连接new ArrayList<>()// 扩展);}

2.3.Docket 实例关联上 apiInfo()

@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
}

2.4.重启项目,访问测试 http://localhost:8080/swagger-ui.html 看下效果;
在这里插入图片描述

3.配置Swagger扫描接口

3.1构建Docket时通过select()方法配置怎么扫描接口

@Bean
public Docket docket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()// 通过.select()方法,去配置扫描接口,RequestHandlerSelectors配置如何扫描接口.apis(RequestHandlerSelectors.basePackage("com.apesource.swagger.controller")).build();
}

3.2.重启项目测试,由于我们配置根据包的路径扫描接口,所以我们只能看到一个类
在这里插入图片描述
3.3除了通过包路径配置扫描接口外,还可以通过配置其他方式扫描接口,这里注释一下所有的配置方式:

  • any(): 扫描所有,项目中的所有接口都会被扫描到
  • none(): 不扫描接口
  • withMethodAnnotation(final Class<? extends Annotation> annotation):通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求
  • withClassAnnotation(final Class<? extends Annotation> annotation):通过方法上的注解扫描,如withMethodAnnotation(GetMapping.class)只扫描get请求

3.4可以配置接口扫描过滤
.paths(PathSelectors.ant(“/apesource/**”))
配置如何通过path过滤,即这里只扫描请求以/apesource开头的接口
除了ant还有一些配置:

  • any() // 任何请求都扫描
  • none() // 任何请求都不扫描
  • regex(final String pathRegex) // 通过正则表达式控制
  • ant(final String antPattern) // 通过ant()控制

4.配置API分组

4.1如果没有配置分组,默认是default。通过groupName()方法即可配置分组

    @Beanpublic Docket docket1(){return new Docket(DocumentationType.SWAGGER_2).groupName("group1");}

4.2配置多个分组只需要配置多个docket即可:

@Beanpublic Docket docket1(){return new Docket(DocumentationType.SWAGGER_2).groupName("group1");}@Beanpublic Docket docket2(){return new Docket(DocumentationType.SWAGGER_2).groupName("group2");}

5.拓展:其他皮肤

我们可以导入不同的包实现不同的皮肤定义:
1.默认的访问 http://localhost:8080/swagger-ui.html:

<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version>
</dependency>

2.bootstrap-ui 访问 http://localhost:8080/doc.html

<dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.9.1</version>
</dependency>

在这里插入图片描述
虽然ui界面不同,但功能是相同!


三、常用注解

swagger通过注解生成接口文档,包括接口名、请求方法、参数、返回信息的等等。

1.接口注解

@Api:修饰整个类,描述Controller的作用
语法:@Api(tags=“说明该类的作用,可以在UI界面上看到的注解”,value = “/类的访问路径”, description = “类的文字描述”)

@RequestMapping("/user")
@Api(tags = "UserController|一个用来测试swagger注解的控制器1",value = "/user")
public class UserController {
}

2.方法及参数注解

在高版主的Swagger中,Swagger会自动帮我们识别简单的参数及请求信息:

  1. @ApiOperation:描述一个类的一个方法,说明方法的作用
    语法:@ApiOperation(value = “接口说明”, httpMethod = “接口请求方式”, response = “接口返回参数类型”, notes = “接口发布说明”)
	@GetMapping(value ="/findByName")@ApiOperation(value="根据用户名查询", notes="描述的具体信息可以省略",httpMethod="GET",response = Result.class)public Result findByName(@RequestParam String userName){}

在这里插入图片描述

  1. @ApiImplicitParam:一个请求参数
    语法:@ApiImplicitParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”)

  2. @ApiImplicitParams: 多个请求参数
    @ApiImplicitParams(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”)

  3. @ApiParam:单个参数描述
    语法:@ApiParam(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”)

  4. @ApiParams:多个参数描述
    语法:@ApiParams(required = “是否必须参数”, name = “参数名称”, value = “参数具体描述”,dateType="变量类型”,paramType="请求方式”)

  5. @ApiResponse:HTTP响应其中1个描述,响应配置
    语法:@ApiResponse(code = 400, message = “Invalid user supplied”)

  6. @ApiResponses:HTTP响应整体描述
    语法:@ApiResponses({ @ApiResponse(code = 400, message = “Invalid Order”) })

在这里插入图片描述

3.实体类注解

  1. @ApiModel:用对象实体来作为入参;
  2. @ApiModelProperty:用于描述字段信息;
  3. @ApiProperty:用对象接实体收参数时,描述对象的一个字段;
  4. @ApiIgnore:使用该注解忽略这个API;
  5. @ApiError :发生错误返回的信息。
@ApiModel(value = "控制器方法返回值",description = "自定义结果集")
public class Result {@ApiModelProperty(name = "falge",value = "结果集状态",example = "true")private boolean falge;//状态@ApiModelProperty(name = "message",value = "提示信息",example = "查询成功")private String message;//提示信息@ApiModelProperty(name = "data",value = "返回数据")private Object data;//返回数据}

效果如图:
在这里插入图片描述

总结

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

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

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

相关文章

一种影像比对快速提取建筑物要素变化的方法

李和军1,2 李 敏3 李楚钰1,2 唐廷元1,2 胡日查4 (1. 北京市测绘设计研究院, 北京, 100038;2. 城市空间信息工程北京市重点实验室, 北京 100038;3. 北京市地质矿产勘查院信息中心, 北京, 100195;4. 内蒙古测绘地理信息中心, 内蒙古 呼和浩特, 010000) 摘 要&#xff1a;本文围绕…

【LeetCode每日一题合集】2023.8.28-2023.9.3(到家的最少跳跃次数)

文章目录 57. 插入区间823. 带因子的二叉树解法——递推 1654. 到家的最少跳跃次数(BFS&#xff0c;&#x1f6b9;最远距离上界的证明)1761. 一个图中连通三元组的最小度数2240. 买钢笔和铅笔的方案数解法1——完全背包解法2——枚举买了几支钢笔&#xff08;推荐解法&#xff…

qt简易网络聊天室 数据库的练习

qt网络聊天室 服务器&#xff1a; 配置文件.pro QT core gui networkgreaterThan(QT_MAJOR_VERSION, 4): QT widgetsCONFIG c11# The following define makes your compiler emit warnings if you use # any Qt feature that has been marked deprecated (the exac…

Kafka3.0.0版本——文件清理策略

目录 一、文件清理策略1.1、文件清理策略的概述1.2、文件清理策略的官方文档1.3、日志超过了设置的时间如何处理1.3.1、delete日志删除&#xff08;将过期数据删除&#xff09;1.3.2、compact日志压缩 一、文件清理策略 1.1、文件清理策略的概述 Kafka 中默认的日志保存时间为…

Cento7 Docker-compose安装以及使用InfluxDB

InfluxDB是一个时序数据库&#xff0c;主要用于监控场景的数据支撑&#xff0c;对于那些写少读多按时间序查询数据的场景是非常适用的。接下来我们用docker-compose的形式安装。首先先装好docker,docker-compose命令 yum -y install yum-utils device-mapper-persistent-data…

【买华为云产品,返CSDN余额红包】,快来薅羊毛!

华为云828营销季火热进行中&#xff0c;9月15日前首次购买华为云产品官网任意一款产品&#xff0c;可获得相应比例的CSDN红包。 热门产品云服务器、域名、商标、主机安全等产品都在其中&#xff0c;任君挑选。 活动优惠价购买后还是获得相应比例余额红包&#xff0c;实际付费金…

游戏软件报错d3dx9_43.dll丢失怎么解决?这5个解决方法可以修复

我想和大家分享一个关于电脑问题的话题——d3dx9_43.dll丢失怎么解决。这个话题对于很多使用电脑的朋友来说&#xff0c;可能是一个非常棘手的问题。d3dx9_43.dll是 DirectX中非常重要的一部分&#xff0c;许多游戏和应用程序都需要它来正常运行。如果丢失了这个文件&#xff0…

Simulink建模与仿真(3)-Simulink 简介

分享一个系列&#xff0c;关于Simulink建模与仿真&#xff0c;尽量整理成体系 1、Simulink特点 Simulink是一个用来对动态系统进行建模、仿真和分析的软件包。使用Simulink来建模、分析和仿真各种动态系统(包括连续系统、离散系统和混合系统)&#xff0c;将是一件非常轻松的事…

万物互联:软件与硬件的协同之道

在当今数字化时代&#xff0c;我们身边的一切似乎都与计算机和互联网有关。从智能手机到智能家居设备&#xff0c;从自动驾驶汽车到工业生产线&#xff0c;无论我们走到哪里&#xff0c;都能看到软件和硬件的协同作用。本文将探讨这种协同作用&#xff0c;解释软件和硬件如何相…

ThreadLocal

ThreadLocal 参考&#xff1a;https://blog.csdn.net/u010445301/article/details/111322569 ThreadLocal简介 作用&#xff1a;实现线程范围内的局部变量&#xff0c;即ThreadLocal在一个线程中是共享的&#xff0c;在不同线程之间是隔离的。 原理&#xff1a;ThreadLocal存…

c高级day1(9.6) 离线软件安装,文件相关指令,文件权限相关指令,

作业: 使用cut截取出Ubuntu用户的家目录&#xff0c;要求&#xff1a;不能使用":"作为分割 不会 Xmind&#xff1a;

vue2踩坑之项目:生成二维码使用vue-print-nb打印二维码

1. vue2安装 npm install vue-print-nb --save vue3安装 npm install vue3-print-nb --save 2. //vue2 引入方式 全局 main.js import Print from vue-print-nb Vue.use(Print) ------------------------------------------------------------------------------------ //vue2 …

WEBGL(4):动态绘制点并根据详细自定义颜色

1 实现代码 <!DOCTYPE html> <html lang"en"><head><meta charset"UTF-8"><meta http-equiv"X-UA-Compatible" content"IEedge"><meta name"viewport" content"widthdevice-width, …

前端面试中Vue的有经典面试题三

11. 网页从输入网址到渲染完成经历了哪些过程&#xff1f; 大致可以分为如下7步&#xff1a; 输入网址&#xff1b; 发送到DNS服务器&#xff0c;并获取域名对应的web服务器对应的ip地址&#xff1b; 与web服务器建立TCP连接&#xff1b; 浏览器向web服务器发送http请求&a…

windows 不能ping通虚拟机问题

先查看windows网卡 查看虚拟机种 对应VMnet8种的 nat &#xff08;我用的是这种连接方式&#xff09;设置 问题是不在同一个网段&#xff0c;修改windows VMnet8网卡的配置 保证网关、网段是一样的 现在ping问题解决&#xff0c;也能windows远程连接虚拟机

Bridge Champ举办人机对战赛:NFT游戏与传统竞技共生发展编织新格局

概要 现在,NFT与体育竞技正日益紧密地联系在一起。一些体育项目开始推出与赛事或球队相关的NFT,同时也有部分NFT游戏开始举办电子竞技赛事。这种共生发展正在改变体育竞技的生态。 笔者采访了桥牌冠军项目相关负责人,探讨NFT游戏与传统体育竞技的融合潜力。桥牌冠军近期成功举…

(二十一)大数据实战——Flume数据采集之复制和多路复用案例实战

前言 本节内容我们完成Flume数据采集的一个多路复用案例&#xff0c;使用三台服务器&#xff0c;一台服务器负责采集本地日志数据&#xff0c;通过使用Replicating ChannelSelector选择器&#xff0c;将采集到的数据分发到另外俩台服务器&#xff0c;一台服务器将数据存储到hd…

pytorch-神经网络-手写数字分类任务

Mnist分类任务&#xff1a; 网络基本构建与训练方法&#xff0c;常用函数解析 torch.nn.functional模块 nn.Module模块 读取Mnist数据集 会自动进行下载 %matplotlib inlinefrom pathlib import Path import requestsDATA_PATH Path("data") PATH DATA_PATH / &…

使用 Nacos 在 Spring Boot 项目中实现服务注册与配置管理

&#x1f337;&#x1f341; 博主猫头虎&#xff08;&#x1f405;&#x1f43e;&#xff09;带您 Go to New World✨&#x1f341; &#x1f984; 博客首页——&#x1f405;&#x1f43e;猫头虎的博客&#x1f390; &#x1f433; 《面试题大全专栏》 &#x1f995; 文章图文…

每日刷题(回溯法经典问题之子集)

食用指南&#xff1a;本文为作者刷题中认为有必要记录的题目 前置知识&#xff1a;回溯法经典问题之组合 ♈️今日夜电波&#xff1a;想着你—郭顶 1:09 ━━━━━━️&#x1f49f;──────── 4:15 …