Swagger 概念和使用以及遇到的问题

前言

        接口文档对于前后端开发人员都十分重要。尤其近几年流行前后端分离后接口文档又变
成重中之重。接口文档固然重要,但是由于项目周期等原因后端人员经常出现无法及时更新,
导致前端人员抱怨接口文档和实际情况不一致。
        很多人员会抱怨别人写的接口文档不规范,不及时更新。但是当自己写的时候确实最烦
去写接口文档。这种痛苦只有亲身经历才会牢记于心。
        如果接口文档可以实时动态生成就不会出现上面问题。
        Swagger可以完美的解决上面的问题。

Open API 是什么

         Open API规范(OpenAPI Specification)以前叫做 Swagger 规范,是 REST API 的API
描述格式。
Open API 文件允许描述整个API,包括︰
● 每个访问地址的类型。POST 或 GET。I
● 每个操作的参数。包括输入输出参数。
● 认证方法。
● 连接信息,声明,使用团队和其他信息。
        Open API 规范可以使用 YAML 或 JSON 格式进行编写。这样更利于我们和机器进行
阅读。

        OpenAPI规范 (OAS ) 为 REST API 定义了一个与语言无关的标准接口,允许人和计
算机发现和理解服务的功能,而无需访问源代码,文档或通过网络流量检查。正确定义后,
消费者可以使用最少量的实现逻辑来理解远程服务并与之交互。
        然后,文档生成工具可以使用 OpenAPI 定义来显示 API ,使用各种编程语言生成服务
器和客户端的代码生成工具,测试工具以及许多其他用例。

       

个人理解:Swagger 可以自动的将代码转换成  YAML 或 JSON 格式的接口文档,确保接口文档的实时更新,并且减少写接口文档的痛苦。

swagger 的使用

        在中心仓库搜索 springfox-swagger2,直接使用 swagger 不方便,springfox 对 swagger 进行了封装,可以更方便的使用。

链接:https://mvnrepository.com/artifact/io.springfox/springfox-swagger2

        向 Spring 项目中添加 springfox-swagger2 依赖:

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>3.0.0</version>
</dependency>

        再向项目中添加视图逻辑,这样才可以生成方便查看的接口文档。

        在中心仓库搜索 springfox-swagger-ui

 链接:https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui

向 Spring 项目中添加 springfox-swagger-ui 依赖:

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>3.0.0</version>
</dependency>

@EnableSwagger2

        @EnableSwagger2 是 springfox 提供的一个注解,代表 swagger2 相关技术开启。 加上该注解后会扫描当前类所在包,以及子包中所有类的注解,做 swagger 文档的定值,一般加在启动类上

/*** @EnableSwagger2 是 springfox 提供的一个注解,代表 swagger2 相关技术开启。* 会扫描当前类所在包,以及子包中所有类的注解,做 swagger 文档的定值* */
@SpringBootApplication
@EnableSwagger2
public class SwaggerApplication {public static void main(String[] args) {SpringApplication.run(SwaggerApplication.class, args);}
}

        一般情况下加上 @EnableSwagger2 后就可以直接访问 http://localhost:8080/swagger-ui.html 查看 swagger ui 的界面了

        但是博主遇到了两个问题,一个是直接报错无法运行,一个是 查看 swagger ui 的界面是 404

错误

直接报错无法运行

        此时博主直接尝试运行遇到了一个错误

        这个问题通常发生在 Spring Boot 2.6 及以上版本中,当整合 Swagger 时,由于Spring MVC的路径匹配策略变更导致的兼容性问题。在Spring Boot 2.6版本之后,默认的路径匹配策略由AntPathMatcher 改为了 PathPatternParser,而Swagger(Springfox)仍然使用AntPathMatcher,这就导致了冲突。

        我通过下面的办法解决了问题:

        修改路径匹配策略:在 application.properties 或 application.yml 配置文件中,添加以下配置来指定使用 AntPathMatcher 作为路径匹配策略:

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

查看 swagger ui 的界面是 404

        我们需要创建一个 SwaggerConfig 配置类,在配置类中添加如下配置:

package com.example.swagger.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;/*** @author 全栈学习笔记* @date 2020/4/19 16:00* @description*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2)// 指定构建api文档的详细信息的方法:apiInfo().apiInfo(apiInfo()).select()// 指定要生成api接口的包路径.apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))//使用了 @ApiOperation 注解的方法生成api接口文档//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any())//可以根据url路径设置哪些请求加入文档,忽略哪些请求.build();}/*** 设置api文档的详细信息*/private ApiInfo apiInfo() {return new ApiInfoBuilder()// 标题.title("Spring Boot集成Swagger2")// 接口描述.description("swagger")// 版本信息.version("1.0")// 构建.build();}
}

        就可以正常访问到我们的 swagger ui 界面了

使用 swagger ui 检查接口是否正确

        首先我们先写一些接口类:

@RestController
public class MyController {@GetMapping("/get")public String get(String id){return "get";}@PostMapping("/post")public String post(String id,String name){return "post";}@RequestMapping("/req")public String req(){return "req";}
}

        注意:要在 SwaggerConfig 配置类中加上 MyController  类的包名

        再次访问 swagger ui 界面可以看到已经有了接口信息

        点击一个接口我们可以看到该接口的详细信息,点击 Try it out 可以发起请求检测接口的返回信息

        在方框中输入要传递的参数值 id=1

        点击 Execute 发送请求

        在下面的信息栏就可以查看接口返回的信息,判断接口是否正常工作

swagger 常用注解

@Api 描述类

        用于描述当前类型生成帮助文档的信息(该注解只能用于类上)

属性:

        tags :给当前类型定义别名,可以定义多个。定义几个别名,就在 ui 视图中显示几个控制器访问菜单。

        description :给当前类型生成的帮助文档定义一个描述信息(已经过时了)

@RestController
@RequestMapping("/MyController")
/*** @Api - 描述当前类型生成帮助文档的信息* 属性-*  - tags :给当前类型定义别名,可以定义多个。定义几个别名,就在 ui 视图中显示几个控制器访问菜单。*  - description :给当前类型生成的帮助文档定义一个描述信息(已经过时了)* */
@Api(tags = {"MyController","swagger学习控制器"},description = "测试 api 信息")
public class MyController {@GetMapping("/get")public String get(String id){return "get";}@PostMapping("/post")public String post(String id,String name){return "post";}@RequestMapping("/req")public String req(){return "req";}
}

        可以看到给 MyController 类设置别名后出现了一个新的控制器访问菜单

@ApiOperation 描述方法

        用于描述方法的信息(该注解可以用于类上和方法上,但通常用于方法上)

属性:

        value:对方法的描述信息

        notes:对方法的提示信息 (两个属性的信息所在位置不同)

@RestController
@RequestMapping("/MyController")@Api(tags = {"MyController","swagger学习控制器"},description = "测试 api 信息")
public class MyController {@ApiOperation(value = "get方法,获取客户 id ",notes = "swagger 学习使用 - 处理 GET 请求的方法")@GetMapping("/get")public String get(String id){return "get";}@PostMapping("/post")public String post(String id,String name){return "post";}@RequestMapping("/req")public String req(){return "req";}
}

        如下图,get 方法后有描述信息,post 方法后没有描述信息

点开接口详情,可以看到对该接口的提示信息

@ApiParam 描述参数

        用于描述参数的信息

属性:

        name:参数名称

        value:对参数的描述信息

        required:该参数是否必须(默认是 false)

@RestController
@RequestMapping("/MyController")@Api(tags = {"MyController","swagger学习控制器"},description = "测试 api 信息")
public class MyController {@ApiOperation(value = "get方法,获取客户 id ",notes = "swagger 学习使用 - 处理 GET 请求的方法")@GetMapping("/get")public String get(String id){return "get";}@PostMapping("/post")public String post(@ApiParam(name = "用户 id ",value = "新增用户时用的用户 id ",required = true) String id,@ApiParam(name = "用户名",value = "新增用户时用的用户名",required = true) String name){return "post";}@RequestMapping("/req")public String req(){return "req";}
}

        可以看到属性有了详细的描述信息

@ApiIgnore 忽略

        忽略该注解描述的方法和类,不生产 api 帮助文档

    // @ApiIgnore - 忽略该注解描述的方法和类,不生成 api 帮助文档@ApiIgnore@RequestMapping("/req")public String req(){return "req";}

        如同,添加后由 RequestMapping 产生的多个接口的文档都消失了

@ApiImplicitParams 在方法前描述参数

        在方法前描述参数。

属性:

        name:参数名称

        value:对参数的描述信息

        required:该参数是否必须(默认是 false)

        paramType:该参数的类型

@RestController
@RequestMapping("/MyController")@Api(tags = {"MyController","swagger学习控制器"},description = "测试 api 信息")
public class MyController {@ApiOperation(value = "get方法,获取客户 id ",notes = "swagger 学习使用 - 处理 GET 请求的方法")@GetMapping("/get")@ApiImplicitParams(value = {@ApiImplicitParam(name = "id",value = "前端获取用户id",paramType = "int",required = true),@ApiImplicitParam(name = "name",value = "前端获取用户名",paramType = "字符串")})public String get(String id,String name){return "get";}@PostMapping("/post")public String post(@ApiParam(name = "用户 id ",value = "新增用户时用的用户 id ",required = true) String id,@ApiParam(name = "用户名",value = "新增用户时用的用户名",required = true) String name){return "post";}// @ApiIgnore - 忽略该注解描述的方法和类,不生成 api 帮助文档@ApiIgnore@RequestMapping("/req")public String req(){return "req";}
}

        作用和 @ApiParam 相同,只是写在方法上而已

@ApiModel 与 @ApiModelProperty 描述实体类型

        @ApiModel 与 @ApiModelProperty 描述实体类型,这个实体类型如果成为了接口的返回类型并且该接口生成了接口文档,那么此注解会被解析,生成描述实体类型的文档

@ApiModel(value = "学生实体 - Student ",description = "存储学生信息")
public class Student{@ApiModelProperty(value = "主键",name = "主键(id)",required = true,example = "q",hidden = false)private String id;  //主键@ApiModelProperty(value = "姓名",name = "姓名(name)",required = true,example = "张三",hidden = false)private String name;    //姓名@ApiModelProperty(value = "密码",name = "密码(password)",required = true,example = "123456",hidden = false)private String password;    //密码public Student(){};public String getId() {return id;}public void setId(String id) {this.id = id;}public String getName() {return name;}public void setName(String name) {this.name = name;}public String getPassword() {return password;}public void setPassword(String password) {this.password = password;}
}
    @GetMapping("/getStudentInfo")public Student getStudentInfo(){return new Student();}

        如图,可以查看实体的详细信息

@ApiModel

        描述实体类

属性:

        value:该实体的名称

        description:该实体的描述

@ApiModelProperty

        描述实体类的属性

属性:

        name:属性的名称

        value:属性的描述

        required:是否必须

        example:示例

        hidden:是否隐藏

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

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

相关文章

mysql性能优化-延迟写和异步写优化

MySQL 性能优化中的延迟写和异步写优化是数据库写入操作中非常重要的技术手段。这些技术可以有效减少磁盘 I/O 操作、提高数据库的吞吐量和整体性能。尤其是在高并发写操作场景下&#xff0c;通过优化写入过程&#xff0c;减少阻塞和等待时间&#xff0c;可以大幅度提升系统的响…

Cassandra 5.0 Spring Boot 3.3 CRUD

概览 因AI要使用到向量存储&#xff0c;JanusGraph也使用到Cassandra 卸载先前版本 docker stop cassandra && docker remove cassandra && rm -rf cassandra/运行Cassandra容器 docker run \--name cassandra \--hostname cassandra \-p 9042:9042 \--pri…

【HarmonyOS】深入理解@Observed装饰器和@ObjectLink装饰器:嵌套类对象属性变化

【HarmonyOS】深入理解Observed装饰器和ObjectLink装饰器&#xff1a;嵌套类对象属性变化 前言 之前就Observed和ObjectLink写过一篇讲解博客【HarmonyOS】 多层嵌套对象通过ObjectLink和Observed实现渲染更新处理&#xff01; 其中就Observe监听类的使用&#xff0c;Object…

ZXing.Net:一个开源条码生成和识别器,支持二维码、条形码等

推荐一个跨平台的非常流行的条码库&#xff0c;方便我们在.Net项目集成条码扫描和生成功能。 01 项目简介 ZXing.Net是ZXing的.Net版本的开源库。支持跨多个平台工作&#xff0c;包括 Windows、Linux 和 macOS&#xff0c;以及在 .NET Core 和 .NET Framework 上运行。 解码…

硬件看门狗导致MCU启动时间慢

最近&#xff0c;在项目交付过程中&#xff0c;我们遇到了一个有趣的问题&#xff0c;与大家分享一下。 客户的需求是&#xff1a;在KL15电压上电后&#xff0c;MCU需要在200ms内发送出第一包CAN报文数据。然而&#xff0c;实际测试结果显示&#xff0c;软件需要360ms才能发送…

【通俗易懂介绍OAuth2.0协议以及4种授权模式】

文章目录 一.OAuth2.0协议介绍二.设计来源于生活三.关于令牌与密码的区别四.应用场景五.接下来分别简单介绍下四种授权模式吧1.客户端模式1.1 介绍1.2 适用场景1.3 时序图 2.密码模式2.1 介绍2.2 适用场景2.3时序图 3.授权码模式3.1 介绍3.2 适用场景3.3 时序图 4.简化模式4.1 …

第二百四十一节 JPA教程 - JPA一对一主键连接列示例、JPA一对一映射级联示例

JPA教程 - JPA一对一主键连接列示例 例子 下面的代码来自Person.java。 package cn.w3cschool.common; import javax.persistence.Entity; import javax.persistence.GeneratedValue; import javax.persistence.GenerationType; import javax.persistence.Id; import javax.p…

MES系统如何提升制造企业的运营效率和灵活性

参考拓展&#xff1a;苏州稳联-西门子MES系统-赋能智能制造的核心引擎 制造执行系统(MES)在提升制造企业运营效率和灵活性方面发挥着关键作用。 一、MES系统的基本概念和功能 MES系统是连接企业管理层与生产现场的重要桥梁。它主要负责生产调度、资源管理、质量控制等多个方…

Dockerfile自定义制作镜像,其中10个指令的作用分析

docker容器中 做镜像是重要的技能。 docker commit只能制作比较简单的镜像&#xff0c; 要制作比较完善的镜像&#xff0c; 自定义程度比较高的&#xff0c; 就需要用到dockerfile dockerfile可以回溯历史 动态生成镜像。 FROM是基础镜像 CMD是在容器创建的时候默认的启动命令 …

安全热点问题

安全热点问题 1.DDOS2.补丁管理3.堡垒机管理4.加密机管理 1.DDOS 分布式拒绝服务攻击&#xff0c;是指黑客通过控制由多个肉鸡或服务器组成的僵尸网络&#xff0c;向目标发送大量看似合法的请求&#xff0c;从而占用大量网络资源使网络瘫痪&#xff0c;阻止用户对网络资源的正…

Android webview拦截H5的接口请求并返回处理好的数据

Android webview拦截H5的接口请求并返回处理好的数据 Android 可以通过 WebView 的 shouldInterceptRequest 方法拦截到 H5 中的网络请求。这是一个 WebViewClient 中的回调方法&#xff0c;允许开发者在 WebView 发起网络请求时对其进行处理和修改。 具体使用方法如下&#…

TMStarget学习——T1 Segmentation数据处理及解bug

最新学习季公俊老师的神器 TMStarget 的第一个模块基于结构像的靶区计算T1 segmentation。下面上步骤&#xff1a; (1)在github 上下载 TMStarget https://github.com/jigongjun/Neuroimaging-and-Neuromodulation (2)按照要求下载依赖工具软件AFQ、vistasoft、SPM12 &#…

OpenAI o1团队突破性论文:『过程推理』中数学推理能力大幅提升,从正确中学习的新方法

原创 超 近年来&#xff0c;大型语言模型(LLMs)在复杂的多步推理任务中取得了令人瞩目的进展。这些模型能够生成逐步的思维链&#xff0c;解决从小学数学到高等微积分的各种问题。然而&#xff0c;即使是最先进的模型也常常陷入逻辑陷阱&#xff0c;产生看似合理但实际错误的推…

只装了WPS,DOC文档无法打开

只装了WPS&#xff0c;DOC文档无法打开 打开WPS --> 全局设置 --> 设置 --> 文件格式关联 --> 与office 2007兼容 也可以选择office 2003 或 office 2010 兼容 dox文件的默认打开方式也变为WPS

1.3 计算机网络的分类

欢迎大家订阅【计算机网络】学习专栏&#xff0c;开启你的计算机网络学习之旅&#xff01; 文章目录 前言一、按分布范围分类二、按传输技术分类三、按拓扑结构分类四、按使用者分类五、按传输介质分类 前言 计算机网络根据不同的标准可以被分为多种类型&#xff0c;本章从分布…

iostat 命令:系统状态监控

一、命令简介 ​iostat ​命令用于报告系统中 CPU、磁盘、tty 设备和 CPU 利用率统计信息。 ‍ 需安装 sysstat ​软件包&#xff0c;该软件包提供了一组工具&#xff0c;包括 iostat​、sar​、mpstat ​等&#xff0c;用于系统性能监控和报告。 ‍ 二、命令参数 iostat…

STM32 MPU加速效果测试

测试代码&#xff1a; static volatile uint32_t cnt;cnt 0;uint64_t time time_spent({while (cnt < 1000000){cnt;}});log_info("test time spent: %llu us\r\n", time); 结果&#xff1a; //未开启Cache fmc_ram test: uint32_t spent time: 955963 us uin…

STM32之串口通信

什么是串口 串行通信接口&#xff1a;指按位发送和接收的接口&#xff0c;如RS232/422/485 RS232电平和COMS/TTL电平对比 RS232电平&#xff1a;逻辑1&#xff1a;-15V ~ -3V 逻辑0:3V ~ 15V CMOS电平: 逻辑1&#xff1a;3.3V 逻辑0&#xff1a;0V &#xff08;STM32使用&am…

服务注册中心对比及使用场景分析

目录 引言服务注册中心简介注册中心对比 1. Consul 1.1 介绍1.2 特性1.3 使用场景1.4 AP vs CP 2. Nacos 2.1 介绍2.2 特性2.3 使用场景2.4 AP vs CP 3. ZooKeeper 3.1 介绍3.2 特性3.3 使用场景3.4 AP vs CP 对比表格选择建议总结 引言 随着微服务架构的普及&#xff0c;服…

QT----基于QML的计时器

赶上了实习的末班车,现在在做QML开发,第一天的学习成果,一个计时器.逻辑挺简单的,纯QML实现,代码在仓库QT-Timer 学习使用c的listmodel 学习使用了如何用c的listmodel来存储数据. 新建一个TImeListModel类继承自QAbstractListModel class TimeListModel : public QAbstrac…